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Introduction 

CP/M is a monitor control program for microcomputer system development 
which uses IBM-compatible flexible disks for backup storage. Using a 
computer mainframe based upon Intel's 8080 microcomputer, CP/M 
provides a general environment for program construction, storage, and 
editing, along with assembly and program check-out facilities. An important 
feature of CP/M is that it can be easily altered to execute with any computer 
configuration which uses an Intel 8080 (or Zilog Z-80) Central Processing 
Unit, and has at least 16K bytes of main memory with up to four IBM-com- 
patible diskette drives. Although the standard Digital Research version 
operates on a single-density Intel MDS 800, several different hardware 
manufacturers support their own input-output drivers for CP/M. 

The CP/M monitor provides rapid access to programs through a com- 
prehensive file management package. The file subsystem supports a named 
file structure, allowing dynamic allocation of file space as well as sequential 
and random file access. Using this file system, a large number of distinct 
programs can be stored in both source and machine executable form. 

CP/M also supports a powerful context editor, Intel-compatible assembler, 
and debugger subsystem. Optional software includes a powerful Intel- 
compatible macro assembler, symbolic debugger, along with various 
high-level languages. When coupled with CP/M's Console Command 
Processor, the resulting facilities equal or excel similar largo computer 
facilities. 

CP/M is logically divided into several distinct parts: 

BIOS Basic I/O System (hardware dependent) 

BDOS Basic Disk Operating System 

CCP Console Command Processor 

TPA Transient Program Area 

The BIOS provides the primitive operations necessary to access the diskette 
drives and to interface standard peripherals (teletype, CRT, Paper Tape 
Reader/Punch, and user-defined peripherals), and can be tailored by the 
user for any particular hardware environment by "patching" this portion of 
CP/M. 

The BDOS provides disk management by controlling one or more disk drives 
containing independent file directories. The BDOS implements disk 
allocation strategies which provide fully dynamic file construction while 
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minimizing head movement across the disk during access. Any particular file 
may contain any number of records, not exceeding the size of any single disk. 
In a standard CP/M system, each disk can contain up to 64 distinct files. The 
BDOS has entry points which include the following primitive operations 
which can be programmatically accessed: 

SEARCH Look for a particular disk file by name. 

OPEN Open a file for further operations. 

CLOSE Close a file after processing. 

RENAME Change the name of a particular file. 

READ Read a record from a particular file. 

WRITE Write a record onto the disk. 

SELECT Select a particular disk drive for further operations. 

The CCP provides symbolic interface between the user's console and the 
remainder of the CP/M system. The CCP reads the console device and 
processes commands which include listing the file directory, printing the 
contents of files, and controlling the operation of transient programs, such 
as assemblers, editors, and debuggers. The standard commands which are 
available in the CCP are listed in a following section. 

The last segment of CP/M is the area called the Transient Program Area 
(TPA). The TPA holds programs which are loaded from the disk under 
command of the CCP. During program editing, for example, the TPA holds 
the CP/M text editor machine code and data areas. Similarly, programs 
created under CP/M can be checked out by loading and executing these 
programs in the TPA. 

It should be mentioned that any or all of the CP/M component subsystems 
can be "overlayed" by an executing program. That is, once a user's program 
is loaded into the TPA, the CCP, BDOS, and BIOS areas can be used as the 
program's data area. A "bootstrap" loader is programmatically accessible 
whenever the BIOS portion is not overlayed; thus, the user program need 
only branch to the bootstrap loader at the end of execution, and the complete 
CP/M monitor is reloaded from disk. 



It should be reiterated that the CP/M operating system is partitioned into 
distinct modules, including the BIOS portion which defines the hardware 
environment in which CP/M is executing. Thus, the standard system can be 
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easily modified to any non-standard environment by changing the 
peripheral drivers to handle the custom system. 

An Overview of CP/M 2.0 Facilities 

CP/M 2.0 is a high-performance single-console operating system which uses 
table driven techniques to allow field configuration to match a wide variety 
of disk capacities. All of the fundamental file restrictions are removed, while 
maintaining upward compatibility from previous versions of release 1. 
Features of CP/M 2.0 include field specification of one to sixteen logical 
drives, each containing up to eight megabytes. Any particular file can reach 
the full drive size with the capability to expand to thirty-two megabytes in 
future releases. The directory size can be field configured to contain any 
reasonable number of entries, and each file is optionally tagged with 
read /only and system attributes. Users of C P/M 2.0 are physically separated 
by user numbers, with facilities for file copy operations from one user area to 
another. Powerful relative-record random access functions are present in 
CP/M 2.0 which provide direct access to any of the 65536 records of an eight 
megabyte file. 

All disk-dependent portions of CP/M 2.0 are placed into a BIOS-resident 
"disk parameter block" which is either hand coded or produced automat- 
ically using the disk definition macro library provided with CP/M 2.0. The 
end user need only specify the maximum number of active disks, the starting 
and ending sector numbers, the data allocation size, the maximum extent of 
the logical disk, directory size information, and reserved track values. The 
macros use this information to generate the appropriate tables and table 
references for use during CP/M 2.0 operation. Deblocking information is also 
provided which aids in assembly or disassembly of sector sizes which are 
multiples of the fundamental 128 byte data unit, and the system alteration 
manual includes general-purpose subroutines which use this deblocking 
information to take advantage of larger sector sizes. Use of these 
subroutines, together with the table driven data access algorithms, make 
CP/M 2.0 truly a universal data management system. 

File expansion is achieved by providing up to 512 logical file extents, where 
each logical extent contains 16K bytes of data. CP/M 2.0 is structured, 
however, so that as much as 128K bytes of data is addressed by a single 
physical extent (corresponding to a single directory entry), thus maintaining 
compatibility with previous versions while takingfull advantage of directory 
space. 

Random access facilities are present in CP/M 2.0 which allow immediate 
reference to any record of an eight megabyte file. Using CP/M's unique data 
organization, data blocks are only allocated when actually required and 
movement to a record position requires little search time. Sequential file 
access is upwardly compatible from earlier versions to the full eight 
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megabytes, while random access compatibility stops at 512K byte files. Due 
to CP/M 2.0's simpler and faster random access, application programmers 
are encouraged to alter their programs to take full advantage of the 2.0 
facilities. 

Several CP/M 2.0 modules and utilities have improvements which 
correspond to the enhanced file system. STAT and PIP both account for file 
attributes and user areas, while the CCP provides a "login" function to 
change from one user area to another. The CCP also formats directory 
displays in a more convenient manner and accounts for both CRT and 
hard-copy devices in its enhanced line editing functions. 

Functional Description of CP/M 

The user interacts with CP/M primarily through the CCP, which reads and 
interprets commands entered through the console. In general, the CCP 
addresses one of several disks which are online (the standard system 
addresses up to four different disk drives). These disk drives are labelled A, 
B, C, and D. A disk is "logged in" if the CCP is currently addressing the disk. 
In order to clearly indicate which disk is the currently logged disk, the CCP 
always prompts the operator with the disk name followed by the symbol ">" 
indicating that the CCP is ready for another command. Upon initial start up, 
the CP/M system is brought in from disk A, and the CCP displays the 
message 

xxK CP/M VER m.m 

where xx is the memory size (in kilobytes) which this CP/M system manages, 
and m.m is the CP/M version number. All CP/M systems are initially set to 
operate in a 16K memory space, but can be easily reconfigured to fit any 
memory size on the host system. Following system signon, CP/M automat- 
ically logs in disk A, prompts the user with the symbol "A > " (indicating that 
CP/M is currently addressing disk "A"), and waits for a command. The 
commands are implemented at two levels: built-in commands and transient 
commands. 



General Command Structure 

Built-in commands are a part of the CCP program itself, while transient 
commands are loaded into the TPA from disk and executed. The built-in 
commands are 

ERA Erase specified files. 

DIR Displays file names in the directory. 
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REN Rename the specified file. 

SAVE Save memory contents in a file. 

TYPE Type the contents of a file on the logged disk. 

USER Move to another area within the same directory. 

Nearly all of the commands reference a particular file or group of files. The 
form of a file reference is specified below. 

File References 

A file reference identifies a particular file or group of files on a particular disk 
attached to CP/M. These file references can be either "unambiguous" (ufn) 
or "ambiguous" (afn). An unambiguous file reference uniquely identifies a 
single file, while an ambiguous file reference may be satisfied by a number of 
different files. 

File references consist of two parts: the primary name and the secondary 
name. Although the secondary name is optional, it usually isgeneric; that is, 
the secondary name "ASM;' for example, is used to denote that the file is an 
assembly language source file, while the primary name distinguishes each 
particular source file. The two names are separated by a "." as shown below: 

pppppppp.sss 

where pppppppp represents the primary name of eight characters or less, and 
sss is the secondary name of no more than three characters. As mentioned 
above, the name 

pppppppp 

is also allowed and is equivalent to a secondary name consisting of three 
blanks. The characters used in specifying an unambiguous file reference 
cannot contain any of the special characters 

<>.,;: = ?*[] 

while all alphanumerics and remaining special characters are allowed. 

An ambiguous file reference is used for directory search and pattern 
matching. The form of an ambiguous file reference is similar to an 
unambiguous reference, except the symbol "?" may be interspersed 
throughout the primary and secondary names. In various commands 
throughout CP/M, the "?" symbol matches any character of a file name in 
the "?" position. Thus, the ambiguous reference 

3-7 



X?Z.C?M 

is satisfied by the unambiguous file names 

XYZ.COM 
and 

X3Z.CAM 

Note that the ambiguous reference 

is equivalent to the ambiguous file reference 

????????.??? 

while 

pppppppp.* 
and 

*.sss 

are abbreviations for 

pppppppp.??? 



and 



???????? 



sss 



respectively. As an example, 

DIR *.* 

is interpreted by the CCP as a command to list the names of all disk files in 
the directory, while 

DIR X.Y 

searches only for a file by the name X.Y. Similarly, the command 

DIR X?Y.C?M 

causes a search for all (unambiguous) file names on the disk which satisfy this 
ambiguous reference. 

3-8 



The following file names are valid unambiguous file references: 

X XYZ GAMMA 

X.Y XYZ.COM GAMMA.l 

As an added convenience, the programmer can generally specify the disk 
drive name along with the file name. In this case, the drive name is given as 
a letter A through Z followed by a colon ( : ). The specified drive is then "logged 
in" before the file operation occurs. Thus, the following are valid file names 
with disk name prefixes: 

A:XY B:XYZ C:GAMMA 

Z:XYZ.COM B:X.A?M C:*.ASM 

It should also be noted that all alphabetic lower case letters in file and drive 
names are always translated to upper case when they are processed by the 
CCP. 

Switching Disks 

The operator can switch the currently logged disk by typing the disk drive 
name (A, B, C, or D) followed by a colon (:) when the CCP is waiting for 
console input. Thus, the sequence of prompts and commands shown below 
might occur after the CP/M system is loaded from disk A: 

16K CP/M VER 1.4 

A> DIR List all files on disk A. 

SAMPLE ASM 

SAMPLE PRN 

A>B: Switch to disk B. 

B>Dir *.ASM List all "ASM" files on B. 

DUMP ASM 

FILES ASM 

B>A: Switch back to A. 

Form of Built-in Commands 

The file and device reference forms described above can now be used to fully 
specify the structure of the built-in commands. In the description below, 
assume the following abbreviations: 

ufn unambiguous file reference 

afn ambiguous file reference 

cr carriage return 

Further, recall that the CCP always translates lower case characters to 
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upper case characters internally. Thus, lower case alphabetics are treated as 
if they are upper case in command names and file references. 

ERAse Command 

ERA afn 

The ERA (erase) command removes files from the currently logged-in disk 
(i.e., the disk name currently prompted by CP/M preceding the ">"). The 
files which are erased are those which satisfy the ambiguous file reference 
afn. The following examples illustrate the use of ERA: 



ERA X.Y 



The file named X.Y on the currently logged disk 
is removed from the disk directory, and the space 
is returned. 



ERAX.* 



All files with primary name X are removed from 
the current disk. 



ERA *.ASM 



All files with secondary name ASM are removed 
from the current disk. 



ERA X?Y.C?M 



All files on the current disk which satisfy the 
ambiguous reference X?Y.C?M are deleted. 



ERA 



Erase all files in the current user's directory. (See 
USER n, page 13.) The CCP prompts with the 
message 

ALL (Y/N)? 
which requires a Y response before files are 
actually removed. 



ERAB:*.PRN 



All files on drive B which satisfy the ambiguous 
reference ????????.PRN are deleted, indepen- 
dently of the currently logged disk. 



DIRectory Command 

DIR afn 

The DIR (directory ) command causes the names of all files which satisfy the 
ambiguous file name afn to be listed at the console device. As a special case, 
the command 

DIR 



lists the files on the currently logged disk (the command "DIR" is equivalent 
to the command "DIR *.*"). Valid DIR commands are shown below. 
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DIR X.Y 

DIR X?Z.C?M 

DIR ??.Y 

Similar to other CCP commands, the afn can be preceded by a drive name. 
The following DIR commands cause the selected drive to be addressed before 
the directory search takes place. 

DIR B: 

DIRB:X.Y 

DIRB:*.A?M 

If no files can be found on the selected diskette which satisfy the directory 
request, then the message "NOT FOUND" is typed at the console. 

REName Command 

REN ufn2 = ufnl 

The REN (rename) command allows the user to change the names of files on 
disk. The file satisfying ufn2 is changed to ufnl. The currently logged disk is 
assumed to contain the file to rename (ufnl). The CCP also allows the user 
to type a left-directed arrow instead of the equal sign, if the user's console 
supports this graphic character. Examples of the REN command are 

REN X.Y = Q.R The file Q.R is changed to X.Y. 

REN XYZ.COM = XYZ.XXX The file XYZ.XXX is changed to 

XYZ.COM. 

The operator can precede either ufnl or ufn2 (or both) by an optional drive 
address. Given that ufnl is preceded by a drive name, then ufn2 is assumed 
to exist on the same drive as ufnl. Similarly, if ufn2 is preceded by a drive 
name, then ufnl is assumed to reside on that drive as well. If both ufnl and 
ufn2 are preceded by drive names, then the same drive must be specified in 
both cases. The following REN commands illustrate this format. 

REN A:X.ASM = YASM The file YASM is changed to X.ASM 

on drive A. 

RENB:ZAP.BAS = ZOTBAS The file ZOT.BAS is changed to 

ZAP.BAS on drive B. 
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REN B:A.ASM = B:A.BAK The file A.BAK is renamed to A.ASM 

on drive B. 

If the file ufnl is already present, the REN command will respond with the 
error "FILE EXISTS" and not perform the change. If ufn2 does not exist on 
the specified diskette, then the message "NOT FOUND" is printed at the 
console. 

SAVE Command 

SAVE n ufn 

The SAVE command places n pages (256-byte blocks) onto disk from the 
TPA and names this file ufn. In the CP/M distribution system, the TPA 
starts at 100H (hexadecimal), which is the second page of memory. Thus, if 
the user's program occupies the area from 100H through 2FFH, the SAVE 
command must specify two pages of memory. The machine code file can be 
subsequently loaded and executed. Examples are: 

SAVE 3 X.COM Copies 100H through 3FFH to 

X.COM. 

SAVE 40 Q Copies 100H through 28FFH to Q 

(note that 28 is the page count in 
28FFH, and that 28H = 2*16 + 8 = 
40 decimal). 

SAVE 4 X.Y Copies 100H through 4FFH to X.Y. 

The SAVE command can also specify a disk drive in the afn portion of the 
command, as shown below. 

SAVE 10 BrZOT.COM Copies 10 pages (100H through 

OAFFH) to the file ZOT.COM on 
drive B. 

The SAVE operation can be used any number of times without altering the 
memory image. 

TYPE Command 

TYPE ufn 

The TYPE command displays the contents of the ASCII source file ufn on 
the currently logged disk at the console device. Valid TYPE commands are 

TYPE X.Y 
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TYPE X.PLM 

TYPE XXX 

The TYPE command expands tabs (clt-I characters), assuming tab 
positions are set at every eighth column. The ufn can also reference a drive 
name as shown below. 

TYPE B:X.PRN The file X.PRN from drive B is displayed. 

USER Command 

USERn 
Where n is an integer value in the range to 15. 

Upon cold start, the operator is automatically "logged" into user area 
number 0. The operator may issue the USER command at any time to move 
to another logical area within the same directory. 

Drives which are logged in while addressing one user number are automat- 
ically active when the operator moves to another user number since a user 
number is simply a prefix which accesses particular directory entries on the 
active disks. 

The active user number is maintained until changed by a subsequent USER 
command, or until a cold start operation when user is again assumed. 

Line Editing and Output Control 

The CCP allows certain line editing functions while typing command lines. 
"Control" indicates that the Control key and the indicated key are to be 
pressed simultaneously. CCP commands can generally be up to 255 
characters in length; they are not acted upon until the carriage return key 
is pressed. 

rubout/delete Remove and echo last character typed 

Control C Reboot CP/M when at beginning of line 

Control E Physical end of line: carriage is returned, but line 

is not sent until the carriage return key is 
depressed. 



3-13 



Control H 



Control J 



Backspace one character position. Produces the 
backspace overwrite function. Can be changed 
internally to another character, such as delete, 
through a simple single byte change. 

Line feed. Terminates current input. 



Control M 



Control R 



Control X 



Carriage return. Terminates input. 

Retype current command line after new line. 

Backspace to beginning of current line. 



The line editor keeps track of the current prompt column position so that the 
operator can properly align data input following a Control R or Control X 
command. 

The control functions Control P and Control S affect console output as 
shown below. 



Control P 



Copy all subsequent console output to the 
currently assigned list device (see the STAT 
command). Output is sent to both the list device 
and the console device until the next Control P is 
typed. 



Control S 



Stop the console output temporarily. Program 
execution and output continue when the next 
character is typed at the console (e.g., another 
Control S). This feature is used to stop output on 
high speed consoles, such as CRT's, in order to 
view a segment of output before continuing. 



Transient Commands 

Transient commands are loaded from the currently logged disk and executed 
in the TPA. The transient commands defined for execution under the CCP 
are shown below. Additional functions can easily be defined by the user (see 
the LOAD command definition). 



STAT 



List the number of bytes of storage remaining on 
the currently logged disk, provide statistical 
information about particular files, and display or 
alter device assignment. 



ASM 



Load the CP/M assembler and assemble the 
specified program from disk. 
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LOAD Load the file in Intel "hex" machine code format 

and produce a file in machine executable form 
which can be loaded into the TPA (this loaded 
program becomes a new command under the 
CCP). 

DDT Load the CP/M debugger into TPA and start 

execution. 

PIP Load the Peripheral Interchange Program for 

subsequent disk file and peripheral transfer 
operations. 

ED Load and execute the CP/M text editor program. 

SUBMIT Submit a file of commands for batch processing. 

DUMP Dump the contents of a file in hex. 

Transient commands are specified in the same manner as built-in commands, 
and additional commands can be easily defined by the user. As an added 
convenience, the transient command can be preceded by a drive name, which 
causes the transient to be loaded from the specified drive into the TPA for 
execution. Thus, the command 

B:STAT 

causes CP/M to temporarily "log in" drive B for the source of the STAT 
transient, and then return to the original logged disk for subsequent 
processing. 

The basic transient commands are listed in detail below. 

STAT 

The STAT command provides general statistical information about file 
storage and device assignment. It is initiated by typing one of the following 
forms: 

STAT 

STAT "command line" 

Special forms of the "command line" allow the current device assignment to 
be examined and altered as well. The various command lines which can be 
specified are shown below, with an explanation of each form shown to the 
right. 
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STAT <cr) 



If the user types an empty command line, the 
STAT transient calculates the storage remaining 
on all active drives, and prints a message 



x: R/W, SPACE: nnnK 
or 

x: R/O, SPACE: nnnK 

for each active drive x, where R/W indicates the 
drive may be read or written, and R/O indicates 
the drive is read only (a drive becomes R/O by 
explicitly setting it to read only, as shown below, 
or by inadvertently changing diskettes without 
performing a warm start). The space remaining 
on the diskette in drive x is given in kilobytes by 



STAT x: <cr) 



If a drive name is given, then the drive is selected 
before the storage is computed. Thus, the com- 
mand "STAT B:" could be issued while logged 
into drive A, resulting in the message 



STAT afn <cr) 



BYTES REMAINING ON B: nnnK 

The command line can also specify a set of files to 
be scanned by STAT. The files which satisfy afn 
are listed in alphabetical order, with storage 
requirements for each file under the heading 



RECS BYTS EX 
rrrr bbbK ee 



D:FILENAMETYP 
d:pppppppp.sss 



where rrrr is the number of 128-byte records 
allocated to the file, bbb is the number of 
kilobytes allocated to the file 
(bbb = rrrr*128/1024), ee is the number of 16K 
extensions (ee = bbb/16), d is the drive name 
containing the file ( A...Z ), pppppppp is the (up to ) 
eight-character primary file name, and sss is the 
(up to) three-character secondary name. After 
listing the individual files, the storage usage is 
summarized. 



STAT x:afn <cr) 



As a convenience, the drive name can be given 
ahead of the afn. In this case, the specified drive 
is first selected, and the form "STAT afn" is 
executed. 
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STAT d:filename.typ $S <cr> 



("d:" is optional drive 
name and "filename.typ" 
is an unambiguous or 
ambiguous file name) 



Produces the output display format: 
Size Recs Bytes Ext Ace 
48 48 6K 1 R/OA:ED.COM 
55 55 12K 1 R/O (A:PIP.COM) 
65536 128 2K 2 R/W A:X.DAT 
The $S parameter causes the "Size" field to be 
displayed. (The command may be used without 
the $S if desired.) The Size field lists the virtual 
file size in records, while the "Recs" field sums the 
number of virtual records in each extent. For files 
constructed sequentially, the Size and Recs 
fields are identical. The "Bytes" field lists the 
actual number of bytes allocated to the corre- 
sponding file. The minimum allocation unit is 
determined at configuration time, and thus the 
number of bytes corresponds to the record count 
plus the remaining unused space in the last 
allocated block for sequential files. Random 
access files are given data areas only when 
written, so the Bytes field contains the only 
accurate allocation figure. In the case of random 
access, the Size field gives the logical end-of-file 
record position and the Recs field counts the 
logical records of each extent (each of these 
extents, however, may contain unallocated 
"holes" even though they are added into the 
record count). The "Ext" field counts the 
number of local 16K extents allocated to the file. 
The "Ace" field gives the R/O or R/W access 
mode, which is changed using the commands 
shown below. The parentheses shown around the 
PIP.COM file name indicate that it has the 
"system " indicator set, so that it will not be listed 
in DIR commands. 



STAT d:filename.typ $R/0 <cr> 

Places the file or set of files in a read-only status 
until changed by a subsequent STAT command. 
The R/O status is recorded in the directory with 
the file so that it remains R/O through inter- 
vening cold start operations. When a file is 
marked R/O, attempts to erase or write into the 
file result in a terminal BDOS message: Bdos Err 
on D: File R/O. 



STAT d:filename.typ $R/W <cr> 

Places the file in a permanent read /write status. 
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STAT d:filename.typ $SYS <cr> 

Attaches the system indicator to the file. 

STAT d:filename.typ $DIR <cr> 

Removes the system indicator from the file. 



STAT d:DSK: <cr> 



Lists the drive characteristics of the disk named 
by "d:" which is in the range A:, B:, ..., P:. The 
drive characteristics are listed in the format: 
d: Drive Characteristics 
65536: 128 Byte Record Capacity 
8192: Kilobyte Drive Capacity 
128: 32 Byte Directory Entries 
0: Checked Directory Entries 
1024: Records/Extent 
128: Records/Block 
58: Sectors/Track 
2: Reserved Tracks 
The total record capacity is listed, followed by 
the total drive capacity listed in Kbytes. The 
number of checked entries is usually identical to 
the directory size for removable media, since this 
mechanism is used to detect changed media 
during CP/M operation without an intervening 
warm start. The number of records per extent 
determines the addressing capacity of each 
directory entry (1024 times 128 bytes, or 128K in 
the example above). The number of records per 
block shows the basic allocation size (in the 
example, 128 records/block times 128 bytes per 
record, or 16K bytes per block) . The listing is then 
followed by the number of physical sectors per 
track and the number of reserved tracks. 



STAT DSK: <cr> 
STAT USR: <cr> 



Lists drive characteristics as above for all 
currently active drives. 

Produces a list of the user numbers which have 
files on the currently addressed disk. The display 
format is: 

Active User : 

Active Files: 013 
where the first line lists the currently addressed 
user number, as set by the last CCP USER 
command, followed by a list of user numbers 
scanned from the current directory. In the above 
case, the active user number is (default at cold 
start), with three user numbers which have 
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active files on the current disk. The operator can 
subsequently examine the directories of the 
other user numbers by logging in with USER 1, 
USER 2, or USER 3 commands, followed by a 
DIR command at the CCP level. 

The STAT command also allows control over the physical to logical device 
assignment (see the IOBYTE function described in the "CP/M Interface 
Guide." In general, there are four logical peripheral devices which are, at any 
particular instant, each assigned to one of several physical peripheral 
devices. The four logical devices are named: 

CON: The system console device (used by CCP for 

communication with the operator) 

RDR: The paper tape reader device 

PUN: The paper tape punch device 

LST: The output list device 

The actual devices attached to any particular computer system are driven by 
subroutines in the BIOS portion of CP/M. Thus, the logical RDR: device, for 
example, could actually be a high speed reader, Teletype reader, or cassette 
tape. In order to allow some flexibility in device naming and assignment, 
several physical devices are defined, as shown below: 

TTY: Teletype device (slow speed console) 

CRT: Cathode ray tube device (high speed console) 

BAT: Batch processing (console is current RDR:, 

output goes to current LST: device) 

UC1: User-defined console 

PTR: Paper tape reader (high speed reader) 

UR1: User-defined reader #1 

UR2: User-defined reader # 2 

PTP: Paper tape punch (high speed punch) 

UP1: User-defined punch # 1 
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UP2: User-defined punch #2 

LPT: Line printer 

UL1: User-defined list device #1 

It must be emphasized that the physical device names may or may not 
actually correspond to devices which the names imply. That is, the PTP: 
device may be implemented as a cassette write operation, if the user wishes. 
The exact correspondence and driving subroutine is defined in the BIOS 
portion of CP/M. In the standard distribution version of CP/M, these 
devices correspond to their names on the MDS 800 development system. 

The command: 

STAT VAL: <cr) 

produces a summary of the available status commands, resulting in the 
output: 

Temp R/O Disk: d:=R/0 

Set Indicator: d:filename.typ $R/0 $R/W $SYS $DIR 

Disk Status: DSK: d:DSK: 

User Status: USR: 

Iobyte Assign: 

CON. = TTY: CRT: BAT: UC1: 

RDR: = TTY: PTR: UR1: UR2: 

PUN: = TTY: PTP: UP1: UP2: 

LST: = TTY: CRT: LPT: UL1: 

In each case, the logical device shown to the left can take any of the four 
physical assignments shown to the right on each line. The current logical to 
physical mapping is displayed by typing the command 

STAT DEV: <cr) 

which produces a listing of each logical device to the left, and the current 
corresponding physical device to the right. For example, the list might 
appear as follows: 
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CON: = CRT 
RDR: = UR1 
PUN: = PTP 
LST: = TTY 

The current logical to physical device assignment can be changed by typing 
a STAT command of the form 

STAT ldl = pdl, ld2 = pd2 ldn = pdn <cr> 

where ldl through ldn are logical device names, and pdl through pdn are 
compatible physical device names (i.e., ldi and pdi appear on the same line in 
the "VAL:" command shown above). The following are valid STAT 
commands which change the current logical to physical device assignments: 

STAT CON: = CRT: <cr> 

STAT PUN: = TTY:,LST: = LPT:, RDR: = TTY: <cr> 



ASMufn 

The ASM command loads and executes the CP/M 8080 assembler. The ufn 
specifies a source file containing assembly language statements where the 
secondary name is assumed to be ASM, and thus is not specified. The 
following ASM commands are valid: 

ASMX 

ASM GAMMA 

The two-pass assembler is automatically executed. If assembly errors occur 
during the second pass, the errors are printed at the console. 

The assembler produces a file 

x.PRN 

where x is the primary name specified in the ASM command. The PRN file 
contains a listing of the source program (with imbedded tab characters if 
present in the source program), along with the machine code generated for 
each statement and diagnostic error messages, if any. The PRN file can be 
listed at the console using the TYPE command, or sent to a peripheral device 
using PIP (see the PIP command structure below). Note also that the PRN 
file contains the original source program, augmented by miscellaneous 
assembly information in the leftmost 16 columns (program addresses and 
hexadecimal machine code, for example). Thus, the PRN file can serve as a 
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backup for the original source file: if the source file is accidentally removed 
or destroyed, the PRN file can be edited (see the ED operator's guide) by 
removing the leftmost 16 characters of each line (this can be done by issuing 
a single editor "macro" command). The resulting file is identical to the 
original source file and can be renamed (REN) from PRN to ASM for 
subsequent editing and assembly. The file 

x.HEX 

is also produced which contains 8080 machine language in Intel "hex" format 
suitable for subsequent loading and execution (see the LOAD command). 
For complete details of CP/M's assembly language program, see the "CP/M 
Assembler Language (ASM) User's Guide!' 

Similar to other transient commands, the source file for assembly can be 
taken from an alternate disk by prefixing the assembly language file name by 
a disk drive name. Thus, the command 

ASM B:ALPHA <cr> 

loads the assembler from the currently logged drive and operates upon the 
source program ALPHA.ASM on drive B. The HEX and PRN files are also 
placed on drive B in this case. 



LOAD ufti cr 

The LOAD command reads the file ufn, which is assumed to contain "hex" 
format machine code, and produces a memory image file which can be 
subsequently executed. The file name ufn is assumed to be of the form 

x.HEX 

and thus only the name x need be specified in the command. The LOAD 
command creates a file named 

x.COM 

which marks it as containing machine executable code. The file is actually 
loaded into memory and executed when the user types the file name x 
immediately after the prompting character ">" printed by the CCP. 

In general, the CCP reads the name x following the prompting character and 
looks for a built-in function name. If no function name is found, the CCP 
searches the system disk directory for a file by the name 
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x.COM 

If found, the machine code is loaded into the TPA, and the program executes. 
Thus, the user need only LOAD a hex file once; it can be subsequently 
executed any number of times by simply typing the primary name. In this 
way, the user can "invent" new commands in the CCP. (Initialized disks 
contain the transient commands as COM files, which can be deleted at the 
user's option.) The operation can take place on an alternate drive if the file 
name is prefixed by a drive name. Thus 

LOAD B:BETA 

brings the LOAD program into the TPA from the currently logged disk and 
operates upon drive B after execution begins. 

It must be noted that the BETA.HEX file must contain valid Intel format 
hexadecimal machine code records (as produced by the ASM program, for 
example) which begin at 100H, the beginning of the TPA. Further, the 
addresses in the hex records must be in ascending order; gaps in unfilled 
memory regions are filled with zeroes by the LOAD command as the hex 
records are read. Thus, LOAD must be used only for creating CP/M standard 
"COM" files which operate in the TPA. Programs which occupy regions of 
memory other than the TPA can be loaded under DDT. 



PIP 

PIP is the CP/M Peripheral Interchange Program which implements the 
basic media conversion operations necessary to load, print, punch, copy, and 
combine disk files. The PIP program is initiated by typing one of the 
following forms 

PIP <cr> 

PIP "command line" <cr) 

In both cases, PIP is loaded into the TPA and executed. In case 1, PIP reads 
command lines directly from the console, prompted with the "*" character, 
until an empty command line is typed (i.e., a single carriage return is issued 
by the operator). Each successive command line causes some media 
conversion to take place according to the rules shown below. Form 2 of the 
PIP command is equivalent to the first, except that the single command line 
given with the PIP command is automatically executed, and PIP terminates 
immediately with no further prompting of the console for input command 
lines. The form of each command line is 

destination = source #1, source #2, ... , source #n <cr) 
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where "destination" is the file or peripheral device to receive the data, and 
"source #1, ..., source #n" represents a series of one or more files or devices 
which are copied from left to right to the destination. 

When multiple files are given in the command line (i.e., n > 1), the individual 
files are assumed to contain ASCII characters, with an assumed CP/M 
end-of-file character (ctl-Z) at the end of each file (see the O parameter to 
override this assumption). The equal symbol ( = ) can be replaced by a 
left-oriented arrow, if your console supports this ASCII character, to 
improve readability. Lower case ASCII alphabetics are internally translated 
to upper case to be consistent with CP/M file and device name conventions. 
Finally, the total command line length cannot exceed 255 characters (ctl-E 
can be used to force a physical carriage return for lines which exceed the 
console width). 



The destination and source elements can be unambiguous references to 
CP/M source files, with or without a preceding disk drive name. That is, any 
file can be referenced with a preceding drive name (A:, B:, C:, or D:) which 
defines the particular drive where the file may be obtained or stored. When 
the drive name is not included, the currently logged disk is assumed. Further, 
the destination file can also appear as one or more of the source files, in which 
case the source file is not altered until the entire concatenation is complete. 
If the destination file already exists, it is removed if the command line is 
properly formed (it is not removed if an error condition arises). The following 
command lines (with explanations to the right) are valid as input to PIP: 

X = Y <cr) Copy to file X from file Y, where X and 

Y are unambiguous file names; Y 
remains unchanged. 

X = Y, Z (cr) Concatenate files Y and Z and copy to 

file X, with Y and Z unchanged. 

X.ASM = YASM,Z.ASM,FIN.ASM <cr) 

Create the file X.ASM from the con- 
catenation of the Y, Z, and FIN files 
with type ASM. 

NEW.ZOT = B:OLD.ZAP <cr) Move a copy of OLD.ZAP from drive B 

to the currently logged disk; name the 
file NEW.ZOT 

B:A.U. = B:B.VA:C.W,D.X <cr) Concatenate file B.V from drive B with 

C.W from drive A and D.X. from the 
logged disk; create the file A.U on drive 
B. 
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For more convenient use, PIP allows abbreviated commands for transferring 
files between disk drives. The abbreviated forms are 

PIP x: = afn <cr> 

PIP x: = y:afn <cr> 

PIP ufn = y: <cr> 

PIP x:ufn = y: <cr> 

The first form copies all files from the currently logged disk which satisfy the 
afn to the same file names on drive x (x = A...Z). The second form is 
equivalent to the first, where the source for the copy is drive y (y = A...Z). The 
third form is equivalent to the command "PIP ufn = y:ufn <cr>" which 
copies the file given by ufn from drive y to the file ufn on drive x. The fourth 
form is equivalent to the third, where the source disk is explicitly given by y. 

Note that the source and destination disks must be different in all of these 
cases. If an afn is specified, PIP lists each ufn which satisfies the afn as it is 
being copied. If a file exists by the same name as the destination file, it is 
removed upon successful completion of the copy, and replaced by the copied 
file. 

The following PIP commands give examples of valid disk-to-disk copy 
operations: 

B: = *.COM <cr) Copy all files which have the secondary name 

"COM" to drive B from the current drive. 

A: = B:ZAR* (cr) Copy all files which have the primary name 

"ZAP" to drive A from drive B. 

ZAPASM = B: <cr> Equivalent to ZAPASM = B:ZAPASM 

B:ZOTCOM = A: <cr> Equivalent to B:ZOT.COM = A:ZOTCOM 

B: = GAMMA.BAS <cr> Same as B:GAMMA.BAS = GAMMA.BAS 

B: = A:GAMMA.BAS <cr> Same as 

B:GAMMA.BAS = A:GAMMA.BAS 

PIP also allows reference to physical and logical devices which are attached 
to the CP/M system. The device names are the same as given under the STAT 
command, along with a number of specially named devices. The logical 
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devices given in the STAT command are 

CON: (console), RDR: (reader), PUN: (punch), and LST: (list) 

while the physical devices are 

TTY: (console, reader, punch, or list) 
CRT: (console, or list), UC1: (console 

PTR: (reader), URl: (reader), UR2: (reader) 
PTP: (punch), UP1: (punch), UP2: (punch) 
LPT: (list), UL1: (list) 

(Note that the "BAT: " physical device is not included, since this assignment 
is used only to indicate that the RDR: and LST: devices are to be used for 
console input/output.) 



The RDR, LST, PUN, and CON devices are all defined within the BIOS 
portion of CP/M, and thus are easily altered for any particular I/O system. 
(The current physical device mapping is defined by IOBYTE; see the 
"CP/M Interface Guide" for a discussion of this function). The destination 
device must be capable of receiving data (i.e., data cannot be sent to the 
punch), and the source devices must be capable of generating data (i.e., the 
LST: device cannot be read). 

The additional device names which can be used in PIP commands are 

NUL: Send 40 "nulls" (ASCII 0's) to the device (this can be issued at the 
end of punched output). 

EOF: Send a CP/M end-of-file (ASCII ctl-Z) to the destination device 
(sent automatically at the end of all ASCII data transfers through 
PIP). 

INP: Special PIP input source which can be "patched" into the PIP 
program itself: PIP gets the input data character-by-character by 
CALLing location 103H, with data returned in location 109H 
(parity bit must be zero). 

OUT: Special PIP output destination which can be patched into the PIP 
program : PIP C ALLs location 106H with data in register C for each 
character to transmit. Note that locations 109H through 1FFH of 
the PIP memory image are not used and can be replaced by special 
purpose drivers using DDT (see the DDT operator's manual). 

PRN: Same as LST:, except that tabs are expanded at every eighth 
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character position, lines are numbered, and page ejects are inserted 
every 60 lines, with an initial eject (same as [t8np]). 

File and device names can be interspersed in the PIP commands. In each 
case, the specific device is read until end-of-file (ctl-Z for ASCII files, and a 
real end of file for non-ASCII disk files). Data from each device or file is 
concatenated from left to right until the last data source has been read. The 
destination device or file is written using the data from the source files, and 
an end-of-file character (ctl-Z) is appended to the result for ASCII files. Note 
that if the destination is a disk file, a temporary file is created ($$$ secondary 
name) which is changed to the actual file name only upon successful 
completion of the copy. Files with the extension "COM" are always assumed 
to be non-ASCII. 

The copy operation can be aborted at any time by depressing any key on the 
keyboard (a rubout suffices). PIP will respond with the message 
"ABORTED" to indicate that the operation was not completed. Note that 
if any operation is aborted, or if an error occurs during processing, PIP 
removes any pending commands which were set up while using the SUBMIT 
command. 

It should also be noted that PIP performs a special function if the destination 
is a disk file with type "HEX" (an Intel hex formatted machine code file), 
and the source is an external peripheral device, such as a paper tape reader. 
In this case, the PIP program checks to ensure that the source file contains 
a properly formed hex file, with legal hexadecimal values and checksum 
records. When an invalid input record is found, PIP reports an error message 
at the console and waits for corrective action. It is usually sufficient to open 
the reader and rerun a section of the tape (pull the tape about 20 inches). 
When the tape is ready for the re-read, type a single carriage return at the 
console, and PIP will attempt another read. If the tape position cannot be 
properly read, simply continue the read (by typing a return following the 
error message), and enter the record manually with the ED program after 
the disk file is constructed. For convenience, PIP allows the end-of-file to be 
entered from the console if the source file is a RDR: device. In this case, the 
PIP program reads the device and monitors the keyboard. If ctl-Z is typed 
at the keyboard, then the read operation is terminated normally. 

Valid PIP commands are shown below. 

PIP LST: = X.PRN <cr> Copy X.PRN to the LST device and termin- 
ate the PIP program. 

PIP <cr> Start PIP for a sequence of commands (PIP 

prompts with "*"). 
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*CON: = X.ASM,Y.ASM,Z.ASM <cr> 

Concatenate three ASM files and copy to the 
CON device. 

♦X.HEX = CON:,Y.HEX,PTR: <cr> 

Create a HEX file by reading the CON (until 
a ctl-Z is typed), followed by data from 
Y.HEX, followed by data from PTR until a 
ctl-Z is encountered. 

*<cr) Single carriage return stops PIP. 

PIP PUN: = NUL:,X.ASM,EOF:,NUL: <cr> 

Send 40 nulls to the punch device; then copy 
the X.ASM file to the punch, followed by an 
end-of-file (ctl-Z) and 40 more null 
characters. 

The user can also specify one or more PIP parameters, enclosed in left and 
right square brackets, separated by zero or more blanks. Each parameter 
affects the copy operation, and the enclosed list of parameters must 
immediately follow the affected file or device. Generally, each parameter can 
be followed by an optional decimal integer value (the S and Q parameters are 
exceptions). The valid PIP parameters are listed below. 

B Block mode transfer: data is buffered by PIP until an ASCII x-off 

character (ctl-S) is received from the source device. This allows 
transfer of data to a disk file from a continuous reading device, such 
as a cassette reader. Upon receipt of the x-off, PIP clears the disk 
buffers and returns for more input data. The amount of data which 
can be buffered is dependent upon the memory size of the host 
system (PIP will issue an error message if the buffers overflow). 

Dn Delete characters which extend past column n in the transfer of 

data to the destination from the character source. This parameter 
is used most often to truncate long lines which are sent to a (narrow ) 
printer or console device. 

E Echo all transfer operations to the console as they are being 

performed. 

F Filter form feeds from the file. All imbedded form feeds are removed. 

The P parameter can be used simultaneously to insert new form 
feeds. 

Gn Get file from user number n. (n is the range 0-15.) Allows one user 

area to receive data files from another. If the operator has issued the 
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USER 4 command at the CCP level, the PIP statement 

PIP X.Y = X.Y[G2] 
reads file X.Y from user number 2 into user area number 4. You 
cannot copy files into a different area than the one which is 
currently addressed by the USER command. 

H Hex data transfer: all data is checked for proper Intel hex file 

format. Non-essential characters between hex records are removed 
during the copy operation. The console will be prompted for 
corrective action in case errors occur. 

I Ignore ":00" records in the transfer of Intel hex format file (the I 

parameter automatically sets the H parameter). 

L Translate upper case alphabetics to lower case. 

N Add line numbers to each line transferred to the destination, 

starting at one, and incrementing by 1. Leading zeroes are 
suppressed, and the number is followed by a colon. If N2 is specified, 
then leading zeroes are included, and a tab is inserted following the 
number. The tab is expanded if T is set. 

Object file (non-ASCII) transfer: the normal CP/M end of file is 

ignored. 

Pn Include page ejects at every n lines (with an initial page eject). If n 

= 1 or is excluded altogether, page ejects occur every 60 lines. If the 
F parameter is used, form feed suppression takes place before the 
new page ejects are inserted. 

Qstz Quit copying from the source device or file when the string s 
(terminated by ctl-Z) is encountered. 

R Read system files. Allows files with the system attribute to be 

included in PIP transfers. Otherwise, system files are not 
recognized. 

Sstz Start copying from the source device when the string s is 
encountered (terminated by ctl-Z). The S and Q parameters can be 
used to "abstract" a particular section of a file (such as a 
subroutine). The start and quit strings are always included in the 
copy operation. 

NOTE — the strings following the s and q parameters are translated 
to upper case by the CCP if form (2) of the PIP command is used. 
Form (1) of the PIP invocation, however, does not perform the 
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automatic upper case translation. 

(1) PIP <cr) 

(2) PIP "command line" <cr> 

Tn Expand tabs (ctl-I characters) to every nth column during the 

transfer of characters to the destination from the source. 

U Translate lower case alphabetics to upper case during the copy 

operation. 

V Verify that data has been copied correctly by rereading after the 

write operation (the destination must be a disk file). 

W Write over R/O files without console interrogation. Under normal 

operation, PIP will not automatically overwrite a file which is set 
to a permanent R/O status. It advises the user of the R/O status 
and waits for overwrite approval. W allows the user to bypass this 
interrogation process. 

Z Zero the parity bit on input for each ASCII character. 

The following are valid PIP commands which specify parameters in the file 
transfer: 

PIP X.ASM = B:[v] <cr) Copy X.ASM from drive B to the current 

drive and verify that the data was properly 
copied. 

PIP LPT: = X.ASM[nt8u] <cr) 

Copy X.ASM to the LPT: device; number 
each line, expand tabs to every eighth column, 
and translate lower case alphabetics to upper 



PIP PUN: = X.HEX[i],Y.ZOT[h] <cr) 

First copy X.HEX to the PUN: device and 
ignore the trailing ":00" record in X.HEX; 
then continue the transfer of data by reading 
Y.ZOT, which contains hex records, including 
any ":00" records which it contains. 

PIP X.LIB = Y.ASM [ sSUBRLTz qJMP L3Tz ] <cr> 

Copy from the file Y.ASM into the file X.LIB. 
Start the copy when the string "SUBR1 : " has 
been found, and quit copying after the string 
" JMP L3" is encountered. 
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PIP PRN: = X.ASM[p50] Send X.ASM to the LST: device, with line 

numbers, tabs expanded to every eighth 
column, and page ejects at every 50th line. 
Note that nt8p60 is the assumed parameter 
list for a PRN file; p50 overrides the default 
value. 

Note that the PIP program itself is initially copied to a user area (so that 
subsequent files can be copied) using the SAVE command. The sequence of 
operations shown below effectively moves PIP from one user area to the 
next. 

USER login user 

DDT PIP.COM load PIP in memory 

(note PIP size s) 

GO return to CCP 

USER 3 login user 3 

SAVE s PIP.com 

where s is the integral number of memory "pages" (256 byte segments) 
occupied by PIP. The number s can be determined when PIP.COM is located 
under DDT, by referring to the value under the "NEXT" display. If for 
example, the next available address is 1DO0, then PIP.COM requires 1C 
hexadecimal pages (or 1 times 16 + 12 = 28 pages), and thus the value of s is 28 
in the subsequent save. Once PIP is copied in this manner, it can then be 
copied to another disk belonging to the same user number through normal 
PIP transfers. 



ED 

The ED program is the CP/M system context editor, which allows creation 
and alteration of ASCII files in the CP/M environment. Complete details of 
operation are given in Chapter 3 CP/M ED. In general, ED allows the 
operator to create and operate upon source files which are organized as a 
sequence of ASCII characters, separated by end-of-line characters (a 
carriage-return line-feed sequence). There is no practical restriction on line 
length (no single line can exceed the size of the working memory), which is 
instead defined by the number of characters typed between (cr)'s. The ED 
program has a number of commands for character string searching, 
replacement, and insertion, which are useful in the creation and correction 
of programs or text files under CP/M. Although the CP/M has a limited 
memory work space area (approximately 5000 characters in a 16K CP/M 
system), the file size which can be edited is not limited, since data is easily 
"paged" through this work area. 

Upon initiation, ED creates the specified source file, if it does not exist, and 
opens the file for access. The programmer then "appends" data from the 
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source file into the work area, if the source file already exists (see the A 
command), for editing. The appended data can then be displayed, altered, 
and written from the work area back to the disk (see the W command). 
Particular points in the program can be automatically paged and located by 
context (see the N command), allowing easy access to particular portions of 
a large file. 

Given that the operator has typed 

ED X.ASM <cr> 

the ED program creates an intermediate work file with the name 

X.$$$ 

to hold the edited data during the ED run. Upon completion of ED, the 
X.ASM file (original file) is renamed to X.BAK, and the edited work file is 
renamed to X.ASM. Thus, the X.BAK file contains the original (unedited) 
file, and the X.ASM file contains the newly edited file. The operator can 
always return to the previous version of a file by removing the most recent 
version, and renaming the previous version. Suppose, for example, that the 
current X.ASM file was improperly edited; the sequence of CCP commands 
shown below would reclaim the backup file. 

DIR X.* Check to see that BAK file is available. 

ERA X.ASM Erase most recent version. 

REN X.ASM = X.BAK Rename the BAK file to ASM. 

Note that the operator can abort the edit at any point (reboot, power failure, 
ctl-C, or Q command) without destroying the original file. In this case, the 
BAK file is not created, and the original file is always intact. 

The ED program also allows the user to "ping-pong" the source and create 
backup files between two disks. The form of the ED command in this case is 

EDufnd: 

where ufn is the name of a file to edit on the currently logged disk and d is the ,, 
name of an alternate drive. The ED program reads and processes the 
source file, and writes the new file to drive d, using the name ufn. Upon 
completion of processing, the original file becomes the backup file. Thus, if 
the operator is addressing disk A, the following command is valid: 
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ED X.ASM B: 

which edits the file X.ASM on drive A, creating the new file X.$$$ on drive 
B. Upon completion of a successful edit, A:X.ASM is renamed to A:X.BAK, 
and B:X.$$$ is renamed to B:X.ASM. For user convenience, the currently 
logged disk becomes drive B at the end of the edit. Note that if a file by the 
name B:X.ASM exists before the editing begins, the message 

FILE EXISTS 

is printed at the console as a precaution against accidentally destroying a 
source file. In this case, the operator must first ERAse the existing file and 
then restart the edit operation. 

Similar to other transient commands, editing can take place on a drive 
different from the currently logged disk by preceding the source file name by 
a drive name. Examples of valid edit requests are shown below 

ED A:X.ASM Edit the file X.ASM on drive A, with new file and 

backup on drive A. 

ED B:X.ASM A: Edit the file X.ASM on drive B to the temporary 

file X.$$$ on drive A. On termination of editing, 
change X.ASM on drive B to X.B AK, and change 
X.$$$ on drive A to X.ASM. 

ED takes file attributes into account. If the operator attempts to edit a 
read/only file, the message 

**FILE IS READ/ONLY** 

appears at the console. The file can be loaded and examined, but cannot be 
altered in any way. Normally the operator simply ends the edit session, and 
uses STAT to change the file attribute to R/W. If the edited file has the 
system attribute set, the message 

"SYSTEM" FILE NOT ACCESSIBLE 

is displayed at the console, and the edit session is aborted. Again, the STAT 
program can be used to change the system attribute if desired. 



SUBMIT 

The SUBMIT command allows CP/M commands to be batched together for 
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automatic processing. The format of SUBMIT is: SUBMIT ufn 
parm #l...parm #n(cr). 

The ufn given in the SUBMIT command must be the filename of a file which 
exists on the currently logged disk, with an assumed file type of "SUB." The 
SUB file contains CP/M prototype commands, with possible parameter 
substitution. The actual parameters parm #1 ... parm #n are substituted 
into the prototype commands, and, if no errors occur, the file of substituted 
commands is processed sequentially by CP/M. 

The prototype command file is created using the ED program, with 
interspersed "$" parameters of the form 

$1 $2 $3 ... $n 

corresponding to the number of actual parameters which will be included 
when the file is submitted for execution. When the SUBMIT transient is 
executed, the actual parameters parm #1 ... parm #n are paired with the 
formal parameters $1 ...$n in the prototype commands. If the number of 
formal and actual parameters does not correspond, then the submit function 
is aborted with an error message at the console. The SUBMIT function 
creates a file of substituted commands with the name 

$$$.SUB 

on the logged disk. When the system reboots (at the termination of the 
SUBMIT), this command file is read by the CCP as a source of input, rather 
than the console. If the SUBMIT function is performed on any disk other 
than drive A, the commands are not processed until the disk is inserted into 
drive A and the system reboots. Further, the user can abort command 
processing at any time by typing a rubout when the command is read and 
echoed. In this case, the $$$.SUB file is removed, and the subsequent 
commands come from the console. Command processing is also aborted if the 
CCP detects an error in any of the commands. Programs which execute 
under CP/M can abort processing of command files when error conditions 
occur by simply erasing any existing $$$.SUB file. 

In order to introduce dollar signs into a SUBMIT file, the user may type a 
"$$" which reduces to a single "$" within the command file. Further, an 
up-arrow symbol " t " may precede an alphabetic character x, which produces 
a single ctl-x character within the file. 



The last command in a SUB file can initiate another SUB file, thus allowing 
chained batch commands. 

Suppose the file ASMBL.SUB exists on disk and contains the prototype 
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commands 

ASM$1 
DIR $1.* 
ERA *.BAK 
PIP$2:=$1.PRN 
ERA $1.PRN 

and the command 

SUBMIT ASMBL X PRN <cr> 

is issued by the operator. The SUBMIT program reads the ASMBL.SUB file, 
substituting "X" for all occurrences of $1 and "PRN" for all occurrences of 
$2, resulting in a $$$.SUB file containing the commands 

ASMX 
DIRX.* 
ERA *.BAK 
PIPPRN:=X.PRN 
ERA X.PRN 

which are executed in sequence by the CCP 

The SUBMIT function can access a SUB file which is on an alternate drive 
by preceding the file name by a drive name. Submitted files are only acted 
upon, however, when they appear on drive A. Thus, it is possible to create a 
submitted file on drive B which is executed at a later time when it is inserted 
in drive A. 



XSUB 

XSUB extends the power of the SUBMIT facility to include character input 
during program execution as well as entering command lines. The XSUB 
command is included as the first line of your submit file and, when executed, 
self-relocates directly below the CCP. 

All subsequent submit command lines are processed by XSUB, so that 
programs which read buffered console input (BDOS function 10) receive 
their input directly from the submit file. For example, the file SAVER.SUB 
could contain the submit lines: 
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XSUB 

DDT 

I$1.HEX 

R 

GO 

SAVE 1 $2.COM 

with a subsequent SUBMIT command: 

SUBMIT SAVER X Y 

which substitutes X for $1 and Y for $2 in the command stream. The XSUB 
program loads, followed by DDT which is sent the command lines 
"IX.HEX" "R" and "GO", thus returning to the CCP. The final command 
"SAVE 1 YCOM" is processed by the CCP. 

The XSUB program remains in memory, and prints the message 

(xsub active) 

on each warm start operation to indicate its presence. Subsequent submit 
command streams do not require the XSUB, unless an intervening cold 
start has occurred. Note that XSUB must be loaded after DESPOOL, if both 
are to run simultaneously. 

DUMP 

The DUMP program types the contents of the disk file (ufn) at the console 
in hexadecimal form. The file contents are listed sixteen bytes at a time, with 
the absolute byte address listed to the left of each line in hexadecimal. Long 
typeouts can be aborted by pushing the rubout key during printout. (The 
source listing of the DUMP program is given in the "CP/M Interface Guide" 
as an example of a program written for the CP/M environment.) 

BDOS Error Messages 

There are three error situations which the Basic Disk Operating System 
intercepts during file processing. When one of these conditions is detected, 
the BDOS prints the message: 

BDOS ERR ON x: error 

where x is the drive name, and "error" is one of the three error messages: 

BAD SECTOR 

SELECT 

R/O 
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The "BAD SECTOR" message indicates that the disk controller electronics 
has detected an error condition in reading or writing the diskette. This 
condition is generally due to a malfunctioning disk controller, or an 
extremely worn diskette. If you find that your system reports this error more 
than once a month, you should check the state of your controller electronics, 
and the condition of your media. You may also encounter this condition in 
reading files generated by a controller produced by a different manufacturer. 
Even though controllers are claimed to be IBM-compatible, one often finds 
small differences in recording formats. The MDS-800 controller, for 
example, requires two bytes of one's following the data CRC byte, which is 
not required in the IBM format. As a result, diskettes generated by the Intel 
MDS can be read by almost all other IBM-compatible systems, while disk 
files generated on other manufacturers' equipment will produce the "BAD 
SECTOR" message when read by the MDS. In any case, recovery from this 
condition is accomplished by typing a ctl-C to reboot (this is the safest! ), or 
a return, which simply ignores the bad sector in the file operation. Note, 
however, that typing a return may destroy your diskette integrity if the 
operation is a directory write, so make sure you have adequate backups in 
this case. 

The "SELECT" error occurs when there is an attempt to address a drive 
beyond the A through D range. In this case, the value of x in the error message 
gives the selected drive. The system reboots following any input from the 
console. 

The R/O (read only) message occurs when there is an attempt to write to 
a diskette which has been designated as read-only in a • STAT command, 
or has been set to read-only by the BDOS. In general, the operator 
should reboot CP/M either by using the warm start procedure ctl-C or 
by performing a cold start whenever the diskettes are changed. If a 
changed diskette is to be read but not written, BDOS allows the diskette 
to be changed without the warm or cold start, but internally marks the 
drive as read-only. The status of the drive is subsequently changed to 
read/write if a warm or cold start occurs. Upon issuing this message, 
CP/M waits for input from the console. An automatic warm start takes 
place following any input. 
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The transient program may use the CP/M I/O facilities to communicate 
with the operator's console and peripheral devices, including the disk 
subsystem. The I/O system is accessed by passing a "function number" and 
an "information address" to CP/M through the FDOS entry point at 
BOOT + 0005H. In the case of a disk read, for example, the transient program 
sends the number corresponding to a disk read, along with the address of an 
FCB to the CP/M FDOS. The FDOS, in turn, performs the operation and 
returns with either a disk read completion indication or an error number 
indicating that the disk read was unsuccessful. The function numbers and 
error indicators are given below. 

Operating System Call Conventions 

The purpose of this section is to provide detailed information for performing 
direct operating system calls from user programs. 

CP/M facilities which are available for access by transient programs fall into 
two general categories: simple device I/O, and disk file I/O. The simple 
device operations include: 

Read a Console Character 
Write a Console Character 
Read a Sequential Tape Character 
Write a Sequential Tape Character 
Write a List Device Character 
Get or Set I/O Status 
Print Console Buffer 
Read Console Buffer 
Interrogate Console Ready 

The FDOS operations which perform disk Input/Output are 

Disk System Reset 

Drive Selection 

File Creation 

File Open 

File Close 

Directory Search 

File Delete 

File Rename 

Random or Sequential Read 

Random or Sequential Write 

Interrogate Available Disks 

Interrogate Selected Disk 

Set DMA Address 

Set/Reset File Indicators 
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As mentioned above, access to the FDOS functions is accomplished by 
passing a function number and information address through the primary 
entry point at location BOOT + 0005H. In general, the function number is 
passed in register C with the information address in the double byte pair DE. 
Single byte values are returned in register A, with double byte values 
returned in HL (a zero value is returned when the function number is out of 
range). For reasons of compatibility, register A = L and register B = H upon 
return in all cases. Note that the register passing conventions of CP/M agree 
with those of Intel's PL/M systems programming language. The list of 
CP/M function numbers is given below. 



System Reset 


19 Delete File 


1 Console Input 


20 Read Sequential 


2 Console Output 


21 Write Sequential 


3 Reader Input 


22 Make File 


4 Punch Output 


23 Rename File 


5 List Output 


24 Return Login Vector 


6 Direct Console I/O 


25 Return Current Disk 


7 Get I/O Byte 


26 Set DMA Address 


8 Set I/O Byte 


27 Get Addr (Alloc) 


9 Print String 


28 Write Protect Disk 


10 Read Console Buffer 


29 Get R/O Vector 


11 Get Console Status 


30 Set File Attributes 


12 Return Version Number 


31 Get Addr (Disk Parms) 


13 Reset Disk System 


32 Set/Get User Code 


14 Select Disk 


33 Read Random 


15 Open File 


34 Write Random 


16 Close File 


35 Compute File Size 


17 Search for First 


36 Set Random Record 


18 Search for Next 





(Functions 28 and 32 should be avoided in application programs to maintain 
upward compatibility with MP/M.) 

Upon entry to a transient program, the CCP leaves the stack pointer set to 
an eight level stack area with the CCP return address pushed onto the stack, 
leaving seven levels before overflow occurs. Although this stack is usually 
not used by a transient program (i.e., most transients return to the CCP 
through a jump to location 0000H), it is sufficiently large to make CP/M 
system calls since the FDOS switches to a local stack at system entry. The 
following assembly language program segment, for example, reads char- 
acters continuously until an asterisk is encountered, at which time control 
returns to the CCP (assuming a standard CP/M system with 
BOOT + 0000H): 
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BDOS 


EQU 


0005H 


CONIN 


EQU 


1 


> 


ORG 


0100H 


NEXTC: 


MVI 


C,CONIN 




CALL 


BDOS 




CPI 


**' 




JNZ 


NEXTC 




RET 






END 





STANDARD CP/M ENTRY 
CONSOLE INPUT FUNCTION 

BASE OF TPA 

READ NEXT CHARACTER 

RETURN CHARACTER IN <A> 

END OF PROCESSING? 

LOOP IF NOT 

RETURN TO CCP 



CP/M implements a named file structure on each disk, providing a logical 
organization which allows any particular file to contain any number of 
records from completely empty, to the full capacity of the drive. Each drive 
is logically distinct with a disk directory and file data area. The disk file 
names are in three parts: the drive select code, the file name consisting of one 
to eight non-blank characters, and the file type consisting of zero to three 
non-blank characters. The file type names the generic category of a 
particular file, while the file name distinguishes individual files in each 
category. The file types listed below name a few generic categories which 
have been established, although they are generally arbitrary: 



ASM 


Assembler Source 


PLI 


PL/ 1 Source File 


PRN 


Printer Listing 


REL 


Relocatable Module 


HEX 


Hex Machine Code 


TEX 


TEX Formatter Source 


BAS 


Basic Source File 


BAK 


ED Source Backup 


INT 


Intermediate Code 


SYM 


SID Symbol File 


COM 


CCP Command File 


$$$ 


Temporary File 



Source files are treated as a sequence of ASCII characters, where each "line" 
of the source file is followed by a carriage-return line-feed sequence (ODH 
followed by OAH). Thus one 128 byte CP/M record could contain several 
lines of source text. The end of an ASCII file is denoted by a control-Z 
character (1AH) or a real end of file, returned by the CP/M read operation. 
Control-Z characters embedded within machine code files (e.g., COM files) 
are ignored, however, and the end of file condition returned by CP/M is used 
to terminate read operations. 

Files in CP/M can be thought of as a sequence of up to 65536 records of 128 
bytes each, numbered from through 65535, thus allowing a maximum of 8 
megabytes per file. Note, however, that although the records may be 
considered logically contiguous, they may not be physically contiguous in 
the disk data area. Internally, all files are broken into 16K byte segments 
called logical extents, so that counters are easily maintained as 8-bit values. 
Although the decomposition into extents is discussed in the paragraphs 
which follow, they are of no particular consequence to the programmer since 
each extent is automatically accessed in both sequential and random access 
modes. 
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In the file operations starting with function number 15, DE usually 
addresses a file control block (FCB). Transient programs often use the 
default file control block area reserved by CP/M at location BOOT + 005CH 
(normally 005CH) for simple file operations. The basic unit of file 
information is a 128 byte record used for all file operations, thus a default 
location for disk I/O is provided by CP/M at location BOOT + 0080H 
(normally 0080H ) which is the initial default DMA address (see function 26). 
All directory operations take place in a reserved area which does not affect 
write buffers as was the case in release 1, with the exception of Search First 
and Search Next, where compatibility is required. 

The File Control Block (FCB) data area consists of a sequence of 33 bytes for 
sequential access and a series of 36 bytes in the case that the file is accessed 
randomly. The default file control block normally located at 005CH can be 
used for random access files, since the three bytes starting at BOOT + 007DH 
are available for this purpose. The FCB format is shown with the following 
fields: 



1* 


fl 


f2 


/ / 


ffi 


tl 


t2 


t3 


ex 


si 


s2 


re 


dO 


/ / 


dn 


cr 


rO 


rl 


r2 


00 


01 


02 


... 08 09 10 11 


12 


13 14 


15 


16 ... 31 32 33 34 


35 


dr 






dr 


ive 


cod« 


3(0 


-16 


) 























fl. ..f8 
tl,t2,t3 



= >use default drive for file 

1 = > auto disk select drive A, 
2= >auto disk select drive B, 

16 = >auto disk select drive P. 

contain the file name in ASCII upper case, with high bit = 

contain the file type in ASCII upper case, with high bit = 

tl', t2', and t3' denote the bit of these positions, 

tl' = l = >Read/Onlyfile, 

t2' = 1 = >SYS file, no DIR list 



ex contains the current extent number, normally set to 00 by the 

user, but in range 0-31 during file I/O 



si reserved for internal system use 

s2 reserved for internal system use, set to zero on call to OPEN, 

MAKE, SEARCH 



record count for extent "ex" takes on values from - 128 
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Introduction 

This manual describes CP/M, release 2, system organization including the 
structure of memory and system entry points. The intention is to provide the 
necessary information required to write programs which operate under 
CP/M, and which use the peripheral and disk I/O facilities of the system. 

CP/M is logically divided into four parts, called the Basic I/O System 
(BIOS), the Basic Disk Operating System (BDOS), the Console command 
processor (CCP), and the Transient Program Area (TPA). The BIOS is a 
hardware-dependent module which defines the exact low level interface to a 
particular computer system which is necessary for peripheral device I/O. 
The BIOS and BDOS are logically combined into a single module with a 
common entry point, and referred to as the FDOS. The CCP is a distinct 
program which uses the FDOS to provide a human-oriented interface to the 
information which is cataloged on the backup storage device. The TPA is an 
area of memory (i.e., the portion which is not used by the FDOS and CCP) 
where various non-resistant operating system commands and user programs 
are executed. The lower portion of memory is reserved for system 
information and is detailed in later sections. Memory organization of the 
CP/M system is shown below: 



high 
memory 

FBASE: 



CBASE: 



TBASE: 
BOOT: 



FDOS (BDOS + BIOS) 



CCP 



TPA 



System parameters 



Base addresses for the two Apple memory configurations that can be used 
with CP/M are shown in the table below: 



Module 

CCP 
BDOS 



44K 


56K (Language Card) 


9400H 


C400H 


9C00H 


CCOOH 
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BIOS AAOOH DAOOH 

Top of RAM AFFFH DFFFH 

All standard CP/M versions assume BOOT = 0000H, which is the base of 
random access memory. The machine code found at location BOOT 
performs a system "warm start" which loads and initializes the programs and 
variables necessary to return control to the CCP. Thus, transient programs 
need only jump to location BOOT to return control to CP/M at the 
command level. Further, the standard versions assume 
TBASE = BOOT + 0100H which is normally location 0100H. The principal 
entry point to the FDOS is at location BOOT + 0005H (normally 0005H) 
where a jump to FBASE is found. The address field at BOOT + 0006H 
(normally 0006H) contains the value of FBASE and can be used to determine 
the size of available memory, assuming the CCP is being overlayed by a 
transient program. 

Transient programs are loaded into the TPA and executed as follows. The 
operator communicates with the CCP by typing command lines following 
each prompt. Each command line takes one of the forms: 

command 
command filel 
command filel file2 

where "command" is either a built-in function such as DIR or TYPE, or the 
name of a transient command or program. If the command is a built-in 
function of CP/M, it is executed immediately. Otherwise, the CCP searches 
the currently addressed disk for a file by the name 

command.COM 

If the file is found, it is assumed to be a memory image of a program which 
executes in the TPA, and thus implicitly originates at TBASE in memory. 
The CCP loads the COM file from the disk into memory starting at TBASE 
and possibly extending up to CBASE. 

If the command is followed by one or two file specifications, the CCP 
prepares one or two file control block (FCB) names in the system parameter 
area. These optional FCB's are in the form necessary to access files through 
the FDOS, and are described in the next section. 

The transient program receives control from the CCP and begins execution, 
perhaps using the I/O facilities of the FDOS. The transient program is 
"called" from the CCP, and thus can simply return to the CCP upon 
completion of its processing, or can jump to BOOT to pass control back to 
CP/M. In the first case, the transient program must not use memory above 
CBASE, while in the latter case, memory up through FBASE-1 is free. 
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The transient program may use the CP/M I/O facilities to communicate 
with the operator's console and peripheral devices, including the disk 
subsystem. The I/O system is accessed by passing a "function number" and 
an "information address" to CP/M through the FDOS entry point at 
BOOT + 0005H. In the case of a disk read, for example, the transient program 
sends the number corresponding to a disk read, along with the address of an 
FCB to the CP/M FDOS. The FDOS, in turn, performs the operation and 
returns with either a disk read completion indication or an error number 
indicating that the disk read was unsuccessful. The function numbers and 
error indicators are given below. 

Operating System Call Conventions 

The purpose of this section is to provide detailed information for performing 
direct operating system calls from user programs. 

CP/M facilities which are available for access by transient programs fall into 
two general categories: simple device I/O, and disk file I/O. The simple 
device operations include: 

Read a Console Character 
Write a Console Character 
Read a Sequential Tape Character 
Write a Sequential Tape Character 
Write a List Device Character 
Get or Set I/O Status 
Print Console Buffer 
Read Console Buffer 
Interrogate Console Ready 



The FDOS operations which perform disk Input/Output are 

Disk System Reset 

Drive Selection 

File Creation 

File Open 

File Close 

Directory Search 

File Delete 

File Rename 

Random or Sequential Read 

Random or Sequential Write 

Interrogate Available Disks 

Interrogate Selected Disk 

Set DMA Address 

Set/ Reset File Indicators 
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As mentioned above, access to the FDOS functions is accomplished by 
passing a function number and information address through the primary 
entry point at location BOOT + 0005H. In general, the function number is 
passed in register C with the information address in the double byte pair DE. 
Single byte values are returned in register A, with double byte values 
returned in HL (a zero value is returned when the function number is out of 
range). For reasons of compatibility, register A = L and register B = H upon 
return in all cases. Note that the register passing conventions of CP/M agree 
with those of Intel's PL/M systems programming language. The list of 
CP/M function numbers is given below. 



System Reset 


19 Delete File 


1 Console Input 


20 Read Sequential 


2 Console Output 


21 Write Sequential 


3 Reader Input 


22 Make File 


4 Punch Output 


23 Rename File 


5 List Output 


24 Return Login Vector 


6 Direct Console I/O 


25 Return Current Disk 


7 Get I/O Byte 


26 Set DMA Address 


8 Set I/O Byte 


27 Get Addr (Alloc) 


9 Print String 


28 Write Protect Disk 


10 Read Console Buffer 


29 Get R/O Vector 


11 Get Console Status 


30 Set File Attributes 


12 Return Version Number 


31 Get Addr (Disk Parms) 


13 Reset Disk System 


32 Set/Get User Code 


14 Select Disk 


33 Read Random 


15 Open File 


34 Write Random 


16 Close File 


35 Compute File Size 


17 Search for First 


36 Set Random Record 


18 Search for Next 





(Functions 28 and 32 should be avoided in application programs to maintain 
upward compatibility with MP/M.) 

Upon entry to a transient program, the CCP leaves the stack pointer set to 
an eight level stack area with the CCP return address pushed onto the stack, 
leaving seven levels before overflow occurs. Although this stack is usually 
not used by a transient program (i.e., most transients return to the CCP 
through a jump to location 0000H), it is sufficiently large to make CP/M 
system calls since the FDOS switches to a local stack at system entry. The 
following assembly language program segment, for example, reads char- 
acters continuously until an asterisk is encountered, at which time control 
returns to the CCP (assuming a standard CP/M system with 
BOOT + 0000H): 
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BDOS 


EQU 


0005H 


CONIN 


EQU 


1 


J 


ORG 


0100H 


NEXTC: 


MVI 


C,CONIN 




CALL 


BDOS 




CPI 


<*» 




JNZ 


NEXTC 




RET 






END 





STANDARD CP/M ENTRY 
CONSOLE INPUT FUNCTION 

BASE OF TPA 

READ NEXT CHARACTER 

RETURN CHARACTER IN <A> 

END OF PROCESSING? 

LOOP IF NOT 

RETURN TO CCP 



CP/M implements a named file structure on each disk, providing a logical 
organization which allows any particular file to contain any number of 
records from completely empty, to the full capacity of the drive. Each drive 
is logically distinct with a disk directory and file data area. The disk file 
names are in three parts: the drive select code, the file name consisting of one 
to eight non-blank characters, and the file type consisting of zero to three 
non-blank characters. The file type names the generic category of a 
particular file, while the file name distinguishes individual files in each 
category. The file types listed below name a few generic categories which 
have been established, although they are generally arbitrary: 



ASM 


Assembler Source 


PLI 


PL/ 1 Source File 


PRN 


Printer Listing 


REL 


Relocatable Module 


HEX 


Hex Machine Code 


TEX 


TEX Formatter Source 


BAS 


Basic Source File 


BAK 


ED Source Backup 


INT 


Intermediate Code 


SYM 


SID Symbol File 


COM 


CCP Command File 


$$$ 


Temporary File 



Source files are treated as a sequence of ASCII characters, where each "line" 
of the source file is followed by a carriage-return line-feed sequence (ODH 
followed by OAH). Thus one 128 byte CP/M record could contain several 
lines of source text. The end of an ASCII file is denoted by a control-Z 
character (1AH) or a real end of file, returned by the CP/M read operation. 
Control-Z characters embedded within machine code files (e.g., COM files) 
are ignored, however, and the end of file condition returned by CP/M is used 
to terminate read operations. 

Files in CP/M can be thought of as a sequence of up to 65536 records of 128 
bytes each, numbered from through 65535, thus allowing a maximum of 8 
megabytes per file. Note, however, that although the records may be 
considered logically contiguous, they may not be physically contiguous in 
the disk data area. Internally, all files are broken into 16K byte segments 
called logical extents, so that counters are easily maintained as 8-bit values. 
Although the decomposition into extents is discussed in the paragraphs 
which follow, they are of no particular consequence to the programmer since 
each extent is automatically accessed in both sequential and random access 
modes. 
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In the file operations starting with function number 15, DE usually 
addresses a file control block (FCB). Transient programs often use the 
default file control block area reserved by CP/M at location BOOT + 005CH 
(normally 005CH) for simple file operations. The basic unit of file 
information is a 128 byte record used for all file operations, thus a default 
location for disk I/O is provided by CP/M at location BOOT + 0080H 
(normally 0080H) which is the initial default DMA address (see function 26). 
All directory operations take place in a reserved area which does not affect 
write buffers as was the case in release 1, with the exception of Search First 
and Search Next, where compatibility is required. 

The File Control Block (FCB) data area consists of a sequence of 33 bytes for 
sequential access and a series of 36 bytes in the case that the file is accessed 
randomly. The default file control block normally located at 005CH can be 
used for random access files, since the three bytes starting at BOOT + 007DH 
are available for this purpose. The FCB format is shown with the following 
fields: 





dr 


fl 


f2 


/ / 


f8 


tl 


t2 


t3 


ex 


si 


s2 


re 


dO 


/ / 


dn 


cr 


rO 


rl 


r2 




00 01 


02 


... 08 09 10 11 


12 


13 14 


15 


16 ... 31 


32 


33 34 


35 


where 






















dr 






dr 


ive 


cod< 


i(0 


-16 


) 























fl. ..ffi 

tl,t2,t3 



= >use default drive for file 

1 = > auto disk select drive A, 

2 = >auto disk select drive B, 

16 = >auto disk select drive P. 

contain the file name in ASCII upper case, with high bit = 

contain the file type in ASCII upper case, with high bit = 

tl', t2', and t3' denote the bit of these positions, 

tl' = l = >Read/Onlyfile, 

t2' = 1 = > SYS file, no DIR list 



ex contains the current extent number, normally set to 00 by the 

user, but in range 0-31 during file I/O 

si reserved for internal system use 

s2 reserved for internal system use, set to zero on call to OPEN, 

MAKE, SEARCH 



record count for extent "ex," takes on values from - 128 
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dO. . .dn filled-in by CP/M, reserved for system use 

cr current record to read or write in a sequential file operation, 

normally set to zero by user 

r0,rl,r2 optional random record number in the range 0-65535, with 

overflow to r2, r0,rl constitute a 16-bit value with low byte rO, 
and high byte rl 



Each file being accessed through CP/M must have a corresponding FCB 
which provides the name and allocation information for all subsequent file 
operations. When accessing files, it is the programmer's responsibility to fill 
the lower sixteen bytes of the FCB and initialize the "cr" field. Normally, 
bytes 1 through 11 are set to the ASCII character values for the file name and 
file type, while all other fields are zero. 

FCB's are stored in a directory area of the disk, and are brought into central 
memory before proceeding with file operations (see the OPEN and MAKE 
functions). The memory copy of the FCB is updated as file operations take 
place and later recorded permanently on disk at the termination of the file 
operation (see the CLOSE command). 

The CCP constructs the first sixteen bytes of two optional FCB's for a 
transient by scanning the remainder of the line following the transient name, 
denoted by "filel" and "file2" in the prototype command line described 
above, with unspecified fields set to ASCII blanks. The first FCB is 
constructed at location BOOT + 005CH, and can be used as-is for subsequent 
file operations. The second FCB occupies the dO . . . dn portion of the first 
FCB, and must be moved to another area of memory before use. If, for 
example, the operator types 

PROGNAME B:X.ZOT Y.ZAP 

the file PROGNAME. COM is loaded into the TPA, and the default FCB at 
BOOT + 005CH is initialized to drive code 2, file name "X" and file type 
"ZOT" The second drive code takes the default value 0, which is placed at 
BOOT + 006CH, with the file name " Y" placed into location BOOT + 006DH 
and file type "ZAP" located 8 bytes later at BOOT + 0075H. All remaining 
fields through "cr" are set to zero. Note again that it is the programmer's 
responsibility to move this second file name and type to another area, usually 
a separate file control block, before opening the file which begins at 
BOOT + 005CH, due to the fact that the open operation will overwrite the 
second name and type. 

If no file names are specifisd in the original command, then the fields 
beginning at BOOT + 005DH and BOOT + 006DH contain blanks. In all 
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cases, the CCP translates lower case alphabetics to upper case to be 
consistent with the CP/M file naming conventions. 

As an added convenience, the default buffer area at location BOOT + 0080H 
is initialized to the command line tail typed by the operator following the 
program name. The first position contains the number of characters, with 
the characters themselves following the character count. Given the above 
command line, the area beginning at BOOT + 0080H is initialized as follows: 



BOOT + 0080H: 






+ 00 +01 +02 +03 +04 +05 +06 


+ 07 


+ 08 +09 +10 +11 +12 +13 +14 


14 " " "B" ":" "X" "." "Z" 


"O" 


"T" " " "Y" "." "Z" "A" "P" 



where the characters are translated to upper case ASCII with unintialized 
memory following the last valid character. Again, it is the responsibility of 
the programmer to extract the information from this buffer before any file 
operations are performed, unless the default DMA address is explicitly 
changed. 

The individual functions are described in detail in the pages which follow. 

FUNCTION 0: System Reset 

Entry Parameters : 
Register C: 00H 

The system reset function returns control to the CP/M operating system at 
the CCP level. The CCP re-initializes the disk subsystem by selecting and 
logging-in disk drive A. This function has exactly the same effect as a jump 
to location BOOT 

FUNCTION 1: CONSOLE INPUT 

Entry Parameters : 
Register C: 01H 

Returned Value : 

Register A: ASCII Character 

The console input function reads the next console character to register A. 
Graphic characters, along with carriage return, line feed, and backspace 
(ctl-H) are echoed to the console. Tab characters (ctl-I) are expanded in / 
columns of eight characters. A check is made for start/stop scroll (ctl-S) and 
start/stop printer echo (ctl-P). The FDOS does not return to the calling 
program until a character has been typed, thus suspending execution of a 
character if not ready. 
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FUNCTION 2: CONSOLE OUTPUT 

Entry Parameters : 

Register C: 02H 

Register E: ASCII Character 

The ASCII character from register E is sent to the console device. Similar to 
function 1, tabs are expanded and checks are made for start/stop scroll and 
printer echo. 

FUNCTION 3: READER INPUT 

Entry Parameters : 

Register C: 03H 

Returned Value : 

Register A: ASCII Character 

The Reader Input function reads the next character from the logical reader 
into register A. Control does not return until the character has been read. 

FUNCTION 4: PUNCH OUTPUT 

Entry Parameters : 

Register C: 04H 

Register E: ASCII Character 

The Punch Output function sends the character from register E to the 
logical punch device. 

FUNCTION 5: LIST OUTPUT 

Entry Parameters : 

Register C: 05H 

Register E: ASCII Character 

The List Output function sends the ASCII character in register E to the 
logical listing device. 
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FUNCTION 6: DIRECT CONSOLE I/O 

Entry Parameters : 

Register C: 06H 
Register E: OFFH (input) or 
char (output) 

Returned Value 

Register A: char or status 
(no value) 

Direct console I/O is supported under CP/M for those specialized 
applications where unadorned console input and output is required. Use of 
this function should, in general, be avoided since it bypasses all of CP/M's 
normal control character functions (e.g., control-S and control-P). 
Programs which perform direct I/O through the BIOS under previous 
releases of CP/M, however, should be changed to use direct I/O under BDOS 
so that they can be fully supported under future releases of MP/M and 
CP/M. 

Upon entry to function 6, register E either contains hexadecimal FF, 
denoting a console input request, or register E contains an ASCII character. 
If the input value is FF, then function 6 returns A = 00 if no character is ready, 
otherwise A contains the next console input character. 

If the input value in E is not FF, then function 6 assumes that E contains a 
valid ASCII character which is sent to the console. 



FUNCTION 7: GET I/O BYTE 

Entry Parameters: 

Register C: 07H 

Returned Value: 
Register A: I/O Byte Value 

The Get I/O Byte function returns the current value of IOBYTE in register 
A. 

FUNCTION 8: SET I/O BYTE 

Entry Parameters : 

Register C: 08H 

Register E: I/O Byte Value 
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The Set I/O Byte function changes the system IOBYTE value to that given 
in register E. 

FUNCTION 9: PRINT STRING 

Entry Parameters : 

Register C: 09H 
Registers DE: String Address 

The Print String function sends the character string stored in memory at the 
location given by DE to the console device, until a "$" is encountered in the 
string. Tabs are expanded asin function 2, and checks are made for start/stop 
scroll and printer echo. 

FUNCTION 10: READ CONSOLE BUFFER 

Entry Parameters : 

Register C: OAH 
Registers DE: Buffer Address 

Returned Value : 

Console Characters in Buffer 

The Read Buffer function reads a line of edited console input into a buffer 
addressed by registers DE. Console input is terminated when either the input 
buffer overflows. The Read Buffer takes the form: 

DE: +0 +1 + 2 +3 +4 +5 +6 +7 +8 ... +n 



mx 


nc 


cl 


c2 


c3 


c4 


c5 


c6 


c7 




?? 



where "mx" is the maximum number of characters which the buffer will hold 
(1 to 255), "nc" is the number of characters read (set by FDOS upon return), 
followed by the characters read from the console. If nc < mx, then 
uninitialized positions follow the last character, denoted by "??" in the above 
figure. A number of control functions are recognized during line editing: 

rub/del removes the echoes the last character 

ctl-C reboots when at the beginning of line 

ctl-E causes physical end of line 

ctl-H backspaces one character position 

ctl-J (line feed) terminates input line 

ctl-M (return) terminates input line 

ctl-R retypes the current line after new line 

ctl-X backspaces to beginning of current line 

Note also that certain functions which return the carriage to the leftmost 
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position (e.g., ctl-X) do so only to the column position where the prompt 
ended (in earlier releases, the carriage returned to the extreme left margin). 
This convention makes operator data input and line correction more legible. 

FUNCTION 11: GET CONSOLE STATUS 

Entry Parameters : 

Register C: OBH 

Return Value 

Register A: Console Status 

The Console Status function checks to see if a character has been typed at 
the console. If a character is ready, the value OFFH is returned in register A. 
Otherwise a 00H value is returned. 

FUNCTION 12: RETURN VERSION NUMBER 

Entry Parameters : 

Register C: OCH 

Returned Value 

Registers HL: Version Number 

Function 12 provides information which allows version independent 
programming. A two-byte value is returned, with H = 00 designating the 
CP/M release (H = 01 for MP/M), and L = 00 for all releases previous to 2.0. 
CP/M 2.0 returns a hexadecimal 20 in register L, with subsequent version 2 
releases in the hexadecimal range 21, 22, through 2F. Using function 12, for 
example, you can write application programs which provide both sequential 
and random access functions, with random access disabled when operating 
under early releases of CP/M. 

FUNCTION 13: RESET DISK SYSTEM 

Entry Parameters : 

Register C: 0DH 

The Reset Disk Function is used to programmatically restore the file system 
to a reset state where all disks are set to read/write (see functions 28 and 29), 
only disk drive A is selected, and the default DMA address is reset to 
BOOT+0080H. This function can be used, for example, by an application 
program which requires a disk change without a system reboot. 
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FUNCTION 14: SELECT DISK 

Entry Parameters : 

Register C: OEH 
Register E: Selected Disk 

The Select Disk function designates the disk drive named in register E as the 
default disk for subsequent file operations, with E = for drive A, 1 for drive 
B, and so-forth through 15 corresponding to drive P in a full sixteen drive 
system. The drive is placed in an "on-line" status which, in particular, 
activates its directory until the next cold start, warm start, or disk system 
reset operation. If the disk media is changed while it is on-line, the drive 
automatically goes to a read/only status in a standard CP/M environment 
(see function 28). FCB's which specify drive code zero (dr = 00H) automat- 
ically reference the currently selected default drive. Drive code values 
between 1 and 16, however, ignore the selected default drive and directly 
reference drives A through P. 

FUNCTION 15 : OPEN FILE 

Entry Parameters : 

Register C: OFH 
Registers DE: FCB Address 

Returned Value 

Register A: Directory Code 

The Open File operation is used to activate a file which currently exists in the 
disk directory for the currently active user number. The FDOS scans the 
referenced disk directory for a match in positions 1 through 14 of the FCB 
referenced by DE (byte si is automatically zeroed), where an ASCII question 
mark (3FH) matches any directory character in any of these positions. 
Normally, no question marks are included and, further, bytes "ex" and "s2" 
of the FCB are zero. 

If a directory element is matched, the relevant directory information is 
copied into bytes dO through dn of the FCB, thus allowing access to the files 
through subsequent read and write operations. Note that an existing file 
must not be accessed until a successful open operation is completed. Upon 
return, the open function returns a "directory code" with the value through 
3 if the open was successful, or OFFH (255 decimal) if the file cannot be found. 
If question marks occur in the FCB then the first matching FCB is activated. 
Note that the current record ("cr") must be zeroed by the program if the file 
is to be accessed sequentially from the first record. 
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FUNCTION 16: CLOSE FILE 

Entry Parameters : 
Register C: 10H 
Registers DE: FCB Address 

Returned Value 

Register A: Directory Code 

The Close File function performs the inverse of the open file function. Given 
that the FCB addressed by DE has been previously activated through an 
open or make function (see functions 15 and 22), the close function 
permanently records the new FCB in the referenced disk directory. The FCB 
matching processfor the close isidentical to the open function. The directory 
code returned for a successful close operation is 0, 1, 2, or 3, while a OFFH (255 
decimal) is returned if the file name cannot be found in the directory. A file 
need not be closed if only read operations have taken place. If write 
operations have occurred, however, the close operation is necessary to 
permanently record the new directory information. 

FUNCTION 17: SEARCH FOR FIRST 

Entry Parameters : 

Register C: 11H 
Registers DE: FCB Address 

Returned Value 

Register A: Directory Code 

Search First scans the directory for a match with the file given by the FCB 
addressed by DE. The value 255 (hexadecimal FF) is returned if the file is not 
found, otherwise 0, 1, 2, or 3 is returned indicating the file is present. In the 
case that the file is found, the current DMA address is filled with the record 
containing the directory entry, and the relative starting position is A * 32 (i.e., 
rotate the A register left 5 bits, or ADD A five times). Although not normally 
required for application programs, the directory information can be 
extracted from the buffer at this position. 

An ASCII question mark (63 decimal, 3F hexadecimal) in any position from 
"fl" through "ex" matches the corresponding field of any directory entry on 
the default or auto-selected disk drive. If the "dr" field contains an ASCII 
question mark, then the auto disk selected function is disabled, the default 
disk is searched, with the search function returning any matched entry, 
allocated or free, belonging to any user number. This latter function is not 
normally used by application programs, but does allow complete flexibility 
to scan all current directory values. If the "dr" field is not a question mark, 
the "s2" byte is automatically zeroed. 
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FUNCTION 18: SEARCH FOR NEXT 

Entry Parameters : 
Register C: 12H 

Returned Value 

Register A: Directory Code 

The Search Next function is similar to the Search First function, except that 
the directory scan continues from the last matched entry. Similar to 
function 17, function 18 returns the decimal value 255 in A when no more 
directory items match. 

FUNCTION 19: DELETE FILE 

Entry Parameters : 

Register C: 13H 
Registers DE: FCB Address 

Returned Value : 

Register A: Directory Code 

The Delete File function removes files which match the FCB addresses by 
DE. The filename and type may contain ambiguous references (i.e., question 
marks in various positions), but the drive select code cannot be ambiguous, 
as in the Search and Search Next functions. 

Function 19 returns a decimal 255 if the referenced file or files cannot be 
found, otherwise a value in the range to 3 is returned. 

FUNCTION 20: READ SEQUENTIAL 

Entry Parameters : 
Register C: 14H 
Registers DE: FCB Address 

Returned Value : 

Register A: Directory Code 

Given that the FCB addressed by DE has been activated through an open or 
make function (numbers 15 and 22), the Read Sequential function reads the 
next 128 byte record from the file into memory at the current DMA address. 
The record is read from position "cr" of the extent, and the "cr" field is 
automatically incremented to the next record position. If the "cr" field 
overflows then the next logical extent is automatically opened and the "cr" 
field is reset to zero in preparation for the next read operation. The value 00H 
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is returned in the A register if the read operation was successful, while a 
non-zero value is returned if no data exists at the next record position (e.g., 
end of file occurs). 

FUNCTION 21: WRITE SEQUENTIAL 

Entry Parameters : 
Register C: 15H 
Registers DE: FCB Address 

Returned Value 

Register A: Directory Code 

Given that the FCB addressed by DE has been activated through an open or 
make function ( numbers 15 and 22 ), the Write Sequential function writes the 
128 byte data record at the current DMA address to the file named by the 
FCB. The record is placed at position "cr" of the file, and the "cr" field is 
automatically incremented to the next record position. If the "cr" field 
overflows then the next logical extent is automatically opened and the "cr" 
field is reset to zero in preparation for the next write operation. Write 
operations can take place into an existing file, in which case newly written 
records overlay those which already exist in the file. Register A = 00H upon 
return from a successful write operation, while a non-zero value indicates an 
unsuccessful write due to a full disk. 

FUNCTION 22: MAKE FILE 

Entry Parameters : 

Register C: 16H 
Registers DE: FCB Address 

Returned Value 

Register A: Directory Code 

The Make File operation is similar to the open file operation except that the 
FCB must name a file which does not exist in the currently referenced disk 
directory (i.e., the one named explicitly by a non-zero "dr" code, or the 
default disk if "dr " is zero) . The FDOS creates the file and initializes both the 
directory and main memory value to an empty file. The programmer must 
ensure that no duplicate file names occur, and a preceding delete operation 
is sufficient if there is any possibility of duplication. Upon return, register 
A =0, 1, 2, or 3 if the operation was successful and OFFH (255 decimal) if no 
more directory space is available. The make function has the side-effect of 
activating the FCB and thus a subsequent open is not necessary. 
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FUNCTION 23: RENAME FILE 

Entry Parameters : 

Register C: 17H 
Registers DE: FCB Address 

Returned Value : 

Register A: Directory Code 

The Rename function uses the FCB addressed by DE to change all 
occurrences of the file named in the first 16 bytes to the file named in the 
second 16 bytes. The drive code "dr" at position is used to select the drive, 
while the drive code for the new file name at position 16 of the FCB is assumed 
to be zero. Upon return, register A is set to a value between and 3 if the 
rename was successful, and OFFH (255 decimal) if the first file name could 
not be found in the directory scan. 

FUNCTION 24: RETURN LOGIN VECTOR 

Entry Parameters : 

Register C: 18H 

Returned Value : 

Registers HL: Login Vector 

The login vector value returned by CP/M is a 16-bit value in HL, where the 
least significant bit of L corresponds to the first drive A, and the high order 
bit of H corresponds to the sixteenth drive, labelled P. A "0" bit indicates that 
the drive is not on-line, while a "1" bit marks a drive that is actively on-line 
due to an explicit disk drive selection, or an implicit drive select caused by a 
file operation which specified a non-zero "dr" field. Note that compatibility 
is maintained with earlier releases, since registers A and L contain the same 
values upon return. 

FUNCTION 25: RETURN CURRENT DISK 

Entry Parameters : 

Register C: 19H 

Returned Value 

Register A: Current Disk 

Function 25 returns the currently selected default disk number in register A. 
The disk numbers range from through 15 corresponding to drives A through 
P. 
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FUNCTION 26: SET DMA ADDRESS 

Entry Parameters : 

Regular C: 1AH 
Registers DE: DMA Address 

"DMA" is an acronym for Direct Memory Address, which is often used in 
connection with disk controllers which directly access the memory of the 
mainframe computer to transfer data to and from the disk subsystem. 
Although many computer systems use non-DMA access (i.e., the data is 
transferred through programmed I/O operations), the DMA address has, in 
CP/M, come to mean the address at which the 128 byte data record resides 
before a disk write and after a disk read. Upon cold start, warm start, or disk 
system reset, the DMA address is automatically set to BOOT + 0080H. The 
Set DMA function, however, can be used to change this default value to 
address another area of memory where the data records reside. Thus, the 
DMA address becomes the value specified by DE until it is changed by a 
subsequent Set DMA function, cold start, warm start, or disk system reset. 

FUNCTION 27: GET ADDR (ALLOC) 

Entry Parameters : 

Register C: 1BH 

Returned Value 

Registers HL: ALLOC Address 

An "allocation vector" is maintained in main memory for each on-line disk 
drive. Various system programs use the information provided by the 
allocation vector to determine the amount of remaining storage (see the 
STAT program). Function 27 returns the base address of the allocation 
vector for the currently selected disk drive. The allocation information may, 
however, be invalid if the selected disk has been marked read/only. Although 
this function is not normally used by application programs, additional 
details of the allocation vector are found in the "CP/M Alteration Guide!' 

FUNCTION 28: WRITE PROTECT DISK 

Entry Parameters : 

Register C: 1CH 

The disk write protect function provides temporary write protection for the 
currently selected disk. Any attempt to write to the disk, before the next cold 
or warm start operation produces the message 

Bdos Err on d: R/O 
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FUNCTION 29: GET READ/ONLY VECTOR 

Entry Parameters : 

Register C: 1DH 

Returned Value : 

Registers HL: R/O Vector Value 

Function 29 returns a bit vector in register pair HL which indicates drives 
which have the temporary read/only bit set. Similar to function 24, the least 
significant bit corresponds to drive A, while the most significant bit 
corresponds to drive P. The R/O bit is set either by the explicit call to 
function 28, or by the automatic software mechanisms within CP/M which 
detect changed disks. 

FUNCTION 30: SET FILE ATTRIBUTES 

Entry Parameters : 

Register C: 1EH 
Registers DE: FCB Address 

Returned Value 

Register A: Directory Code 

The Set File Attributes function allows programmatic manipulation of 
permanent indicators attached to files. In particular, the R/O and System 
attributes (tl' and t2') can be set or reset. The DE pair addresses an 
unambiguous file name with the appropriate attributes set or reset. Function 
30 searches for a match, and changes the matched directory entry to contain 
the selected indicators. Indicators fl' through f4' are not presently used, but 
may be useful for applications programs, since they are not involved in the 
matching process during file open and close operations. Indicators f5' 
through f8' and t3' are reserved for future system expansion. 

FUNCTION 31: GET ADDR (DISK PARMS) 

Entry Parameters : 

Register C: 1FH 

Returned Value 

Registers HL: DPB Address 

The address of the BIOS resident disk parameter block is returned in HL as 
a result of this function call. This address can be used for either of two 
purposes. First, the disk parameter values can be extracted for display and 
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space computation purposes, or transient programs can dynamically change 
the values of current disk parameters when the disk environment changes, if 
required. Normally, application programs will not require this facility. 

FUNCTION 32: SET/GET USER CODE 

Entry Parameters : 

Register C: 20H 
Register E: OFFH (get or 

User Code (set) 

Returned Value : 

Register A: Current Code or 
(no value) 

An application program can change or interrogate the currently active user 
number by calling function 32. If register E = OFFH, then the value of the 
current user number is returned in register A, where the value is in the range 
to 31. If register E is not OFFH, then the current user number is changed to 
the value of E (modulo 32). 

FUNCTION 33: READ RANDOM 

Entry Parameters : 

Register C: 21H 
Registers DE: FCB Address 

Returned Value : 

Register A: Return Code 

The Read Random function is similar to the sequential file read operation of 
previous releases, except that the read operation takes place at a particular 
record number, selected by the 24-bit value constructed from the three byte 
field following the FCB (byte positions rO at 33, rl at 34, and r2 at 35). Note 
that the sequence of 24 bits is stored with least significant byte first (rO), 
middle byte next (rl), and high byte last (r2). CP/M does not reference byte 
r2, except in computing the size of a file (function 35). Byte r2 must be zero, 
however, since a non-zero value indicates overflow past the end of file. 

Thus, the rO,rl byte pair is treated as a double-byte, or "word" value, which 
contains the record to read. This value ranges from to 65535, providing 
access to any particular record of the 8 megabyte file. In order to process a 
file using random access, the base extent (extent 0) must first be opened. 
Although the base extent may or may not contain any allocated data, this 
ensures that the file is properly recorded in the directory, and is visible in DIR 
requests. The selected record number is then stored into the random record 
field (r0,rl ), and the BDOS is called to read the record. Upon return from the 
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call, register A either contains an error code, as listed below, or the value 00 
indicating the operation was successful. In the latter case, the current DMA 
address contains the randomly accessed record. Note that contrary to the 
sequential read operation, the record number is not advanced. Thus, 
subsequent random read operations continue to read the same record. 

Upon each random read operation, the logical extent and current record 
values are automatically set. Thus, the file can be sequentially read or 
written, starting from the current randomly accessed position. Note, 
however, that in this case, the last randomly read record will be re-read as you 
switch from random mode to sequential read, and the last record will be 
re-written as you switch to a sequential write operation. You can, of course, 
simply advance the random record position following each random read or 
write to obtain the effect of a sequential I/O operation. 

Error codes returned in register A following a random read are listed below. 

01 reading unwritten data 

02 (not returning in random mode) 

03 cannot close current extent 

04 seek to unwritten extent 

05 (not returned in read mode) 

06 seek past physical end of disk 

Error code 01 and 04 occur when a random read operation accesses a data 
block which has not been previously written, or an extent which has not been 
created, which are equivalent conditions. Error 3 does not normally occur 
under proper system operation, but can be cleared by simply re-reading, or 
re-opening extent zero as long as the disk is not physically write protected. 
Error code 06 occurs whenever byte r2 is non-zero under the current 2.0 
release. Normally, non-zero return codes can be treated as missing data, with 
zero return codes indicating operation complete. 



FUNCTION 34: WRITE RANDOM 

Entry Parameters : 

Register C: 22H 
Registers DE: FCB Address 

Returned Value : 

Register A: Return Code 

The Write Random operation is initiated similar to the Read Random call, 
except that data is written to the disk from the current DMA address. 
Further, if the disk extent or data block which is the target of the write has 
not yet been allocated, the allocation is performed before the write operation 
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continues. As in the Read Random operation, the random record number is 
not changed as a result of the write. The logical extent number and current 
record positions of the file control block are set to correspond to the random 
record which is being written. Again, sequential read or write operations can 
commence following a random write, with the notation that the currently 
addressed record is either read or rewritten again as the sequential operation 
begins. You can also simply advance the random record position following 
each write to get the effect of a sequential write operation. Note that in 
particular, reading or writing the last record of an extent in random mode 
does not cause an automatic extent switch as it does in sequential mode. 

The error codes returned by a random write are identical to the random read 
operation with the addition of error code 05, which indicates that a new 
extent cannot be created due to directory overflow. 

FUNCTION 35: COMPUTE FILE SIZE 

Entry Parameters : 

Register C: 23H 
Registers DE: FCB Address 

Returned Value : 

Random Record Field Set 

When computing the size of a file, the DE register pair addresses an FCB in 
random mode format (bytes rO, rl, and r2 are present). The FCB contains an 
unambiguous file name which is used in the directory scan. Upon return, the 
random record bytes contain the "virtual" file size which is, in effect, the 
record address of the record following the end of the file. If, following a call 
to function 35, the high record byte r2 is 01, then the file contains the 
maximum record count 65536. Otherwise, bytes rO and rl constitute a 16-bit 
value (rO is the least significant byte, as before) which is the file size. 

Data can be appended to the end of an existing file by simply calling function 
35 to set the random record position to the end of file, then performing a 
sequence of random writes starting at the preset record address 

The virtual size of a file corresponds to the physical size when the file is 
written sequentially. If, instead, the file was created in random mode and 
"holes" exist in the allocation, then the file may in fact contain fewer records 
than the size indicates. If, for example, only the last record of an eight 
megabyte file is written in random mode (i.e., record number 65535), then the 
virtual size is 65536 records, although only one block of data is actually 
allocated. 
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FUNCTION 36: SET RANDOM RECORD 

Entry Parameters : 
Register C: 24H 
Registers DE: FCB Address 

Returned Value 

Random Record Field Set 

The Set Random Record function causes the BDOS to automatically 
produce the random record position from a file which has been read or 
written sequentially to a particular point. The function can be useful in two 
ways. 

First, it is often necessary to initially read and scan a sequential file to extract 
the position of various "key" fields. As each key is encountered, function 36 
is called to compute the random record position for the data corresponding 
to this key. If the data unit size is 128 bytes, the resulting record position is 
placed into a table with the key for later retrieval. After scaning the entire 
file and tabularizing the keys and their record numbers, you can move 
instantly to a particular keyed record by performing a random read using the 
corresponding random record number which was saved earlier. The scheme 
is easily generated when variable record lengths are involved since the 
program need only store the buffer-relative byte position along with the key 
and record number in order to find the exact starting position of the keyed 
data at a later time. 

A second use of function 36 occurs when switching from a sequential read or 
write over to random read or write. A file is sequentially accessed to a 
particular point in the file, function 36 is called which sets the record number, 
and subsequent random read and write operations continue from the 
selected point in the file. 



Sample File-to-File Copy Program 

The program shown below provides a relatively simple example of file 
operations. The program source file is created as COPY.ASM using the 
CP/M ED program and then assembled using ASM or MAC, resulting in a 
"HEX" file. The LOAD program is then used to produce a COPY.COM file 
which executes directly under the CCP The program begins by setting the 
stack pointer to a local area, and then proceeds to move the second name 
from the default area at 006CH to a 33-byte file control block called DFCB. 
The DFCB is then prepared for file operations by clearing the current record 
field. At this point, the source and destination FCB's are ready for processing 
since the SFCB at 005CH is properly set-up by the CCP upon entry to the 
COPY program. That is, the first name is placed into the default FCB, with 
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the proper fields zeroed, including the current record field at 007CH. The 
program continues by opening the source file, deleting any existing 
destination file, and then creating the destination file. If all this is successful, 
the program loops at the label COPY until each record has been read from 
the source file and placed into the destination file. Upon completion of the 
data transfer, the destination file is closed and the program returns to the 
CCP command level by jumping to BOOT. 



sample file-to-file copy program 

at the ccp level, the command 

copy a:x.y b:u.v 

copies the file named x.y from drive 
a to a file named u.v on drive b. 



0000 


= 


boot 


equ 


0000h 


system reboot 


0005 


= 


bdos 


equ 


0005h 


bdos entry point 


5c 


= 


fcbl 


equ 


005ch 


first file name 


5c 


= 


sfcb 


equ 


fcbl 


source fcb 


006c 


= 


fcb2 


equ 


006ch 


second file name 


0080 


= 


dbuff 


equ 


80h 


default buffer 


0100 


= 


tpa 


equ 


0100h 


beginning of tpa 


0009 


= 


pr intf 


equ 


9 


print buffer func# 


0f 


= 


openf 


equ 


15 


open f ile f unci 


0010 


= 


closef 


equ 


16 


close file funct 


0013 


= 


deletef 


equ 


19 


delete file funct 


0014 


= 


readf 


equ 


20 


sequent ial read 


0015 


= 


wr itef 


equ 


21 


sequential write 


0016 


= 


makef 


equ 


22 


make file func# 


100 




'' 


org 


tpa 


beginning of tpa 


0100 


311b0 2 




lxi 


s p , s t a ck 


local stack 






; 


move second file 


name to dfcb 


0103 


0el0 




mvi 


c,16 


half an fcb 


0105 


116c00 




lxi 


d,fcb2 ; 


source of move 


0108 


21da01 




lxi 


h,dfcb 


destination fcb 


010b 


la 


mf cb: 


ldax 


d ; 


source fcb 


010c 


13 




inx 


d ; 


ready next 


010d 


77 




mov 


m,a , 


dest fcb 


010e 


23 




inx 


h ; 


ready next 


010f 


0d 




dcr 


c ; 


count 1 6. . .0 


0110 


c20b01 




jnz 


mf cb 


loop 16 t imes 








name has been mo\ 


ed, zero cr 


0113 


af 




xra 


a 


a = 00h 


0114 


32£a01 




sta 


df cbcr 


current rec = 








source 


and desti 


nation fcb's ready 


0117 


115C00 




lxi 


d,sfcb 


source file 


011a 


cd6901 




call 


open 


error if 255 


011d 


118701 




lxi 


d ,nof ile 


ready message 


0120 


3c 




inr 


a 


255 becomes 


0121 


cc6101 




cz 


finis 


done if no file 








source 


file open 


prep destination 


0124 


llda01 




lxi 


d,dfcb 


destination 


0127 


cd7301 




call 


delete 


remove if present 


012a 


llda01 


' 


lxi 


d.dfcb 


destination 


01 2d 


cd8201 




call 


irake 


create the f ile 


0130 


119601 




lxi 


d ,nodir 


r eaoy message 
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0133 3c 

0134 CC6101 



0137 115C00 copy: 
013a cd7801 
013d b7 
013e C25101 



0141 lldaBl 
0144 Cd7d01 
0147 lla901 
014a b7 
014b C46101 
014e C33701 



inr a ; 255 becomes 3 

cz finis ; done if no dir space 

source file open, best file open 
copy until end of file on source 



eof ile: 



0151 lldaBl 

0154 cd6e01 

0157 21bb01 

015a 3c 

015b CC6101 



015e llcc01 



f inis: 



0161 0e09 
0163 cd0500 
0166 C30000 



0169 0e0f open: 
016b C3O500 

016e 0el0 close: 

0170 C30500 

0173 0el3 delete: 
0175 C30500 

0178 0el4 read: 
017a C3C500 

al7d 0el5 write: 
017£ C30500 

0182 0el 6 make: 
0184 C30500 



lxi 


d,sfcb ; 


source 


call 


read ; 


read next record 


ora 


a ; 


end of file? 


jnz 


eof ile 


skip write if so 


not end 


of file. 


wr ite the record 


lxi 


d,dfcb 


destination 


call 


wr ite 


write record 


lxi 


d , space 


ready message 


ora 


a 


00 if wr ite ok 


en: 


finis 


end i f so 


jmp 


copy 


loop unt il eof 


; end o 


f file, c 


ose destination 


lxi 


d,dfcb 


dest inat ion 


call 


close 


255 if error 


lxi 


h , wr pro t 


ready message 


inr 


a 


255 becomes 00 


cz 


finis 


shouldn't happen 



copy operation complete, end 
lxi d , norma 1 ; ready message 

; write message given by de, reboot 

mvi cprintf 

call bdos ; write message 

jmp boot ; reboot system 

system interface subroutines 
(all return directly from bdos) 



mvi 


c , openf 


jmp 


bdos 


mvi 


c, closef 


jmp 


bdos 


mvi 


c ,deletef 


jmp 


bdos 


mvi 


c , r e ad f 


jmp 


bdos 


mvi 


c , wr i tef 


jmp 


bdos 


mvi 


c, ma kef 


jmp 


bdos 



ls7 6e6f 20fnof ile: 
196 6e6f 209nodir: 
01a9 6f 7574t"space: 
u lob 7 772695wrprot: 
01cc 636f 700normal : 



console messages 

db 'no source fileS' 

db 'no directory space? ' 

db 'out of data space? ' 

db 'write protected?S' 

db 'copy complete?' 





; 


data 


areas 


Blda 


dfeb: 


ds 


33 


Blta = 


bfeber 


equ 


dfcb+32 


Ulfb 


s t a ck : 


6s 


32 


021b 




end 





destination feb 
current record 



; 16 level stack 
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Note that there are several simplifications in this particular program. First, 
there are no checks for invalid file names which could, for example, contain 
ambiguous references. This situation could be detected by scanning the 32 
byte default area starting at location 005CH for ASCII question marks. A 
check should also be made to ensure that the file names have, in fact, been 
included (check locations 005DH and 006DH for non-blank ASCII 
characters). Finally, a check should be made to ensure that the source and 
destination file names are different. A speed improvement could be made by 
buffering more data on each read operation. One could, for example, 
determine the size of memory by fetching FBASE from location 0006H and 
use the entire remaining portion of memory for a data buffer. In this case, the 
programmer simply resets the DMA address to the next successive 128 byte 
area before each read. Upon writing to the destination file, the DMA address 
is reset to the beginning of the buffer and incremented by 128 bytes to the end 
as each record is transferred to the destination file. 

Sample File Dump Utility. 

The file dump program shown below is slightly more complex than the single 
copy program given in the previous section. The dump program reads an 
input file, specified in the CCP command line, and displays the content of 
each record in hexadecimal format at the console. Note that the dump 
program saves the CCP's stack upon entry, resets the stack to a local area, 
and restores the CCP's stack before returning directly to the CCP. Thus, the 
dump program does not perform warm start at the end of processing. 

i DUMP program reads input file and displays hex data 

8100 ' org 188h 

0885 ~ bdos equ 8885h jdoa entry point 

8881 - cons equ 1 jread console 

8882 » typef equ 2 ;type Junction 





org 


bdos 


equ 


cons 


equ 


typer 


equ 


pr intf 


equ 


tarkf 


equ 


epenf 


equ 


readf 


equ 



8889 - printf equ 9 tbuffer print entry 

B«8b * tarkf equ 11 jbreak key function (true if char 

BBBf * epenf equ 15 sfile open 

0814 » read* equ 28 iread function 

885c - fcb equ Sen jfile control block address 

8888 * buff equ 88h linput disk buffer address 

! 

; non graphic characters 

88Bd • cc equ Bdh fcarriage return 

888a = If equ 8ah ;lin« feed 

2 

! file control block definitions 

8B5c « febdn equ fcb+9 ,-disk name 

885d * febfn equ fcb+1 jfile name 

BBSS ■ febft equ fcb+» jdisk file type (3 characters) 

8868 s fcbrl equ fcb+12 jfile's current reel number 

B86b * febrc equ fcb+15 jfile's record count (8 to 128! 

B87c = feber equ fcb+32 jcurrent (next) record number (8 

8»7d » fcbln equ feh+33 ,-fcb length 

: set up stack 

8109 218888 lxi h„8 

8183 39 dad sp 

j entry stack pointer in hi from the ccp 
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8184 221582 shld oldsp . 

; set sp to local stack area (restored at finis) 

8187 315782 lxi sp.stktop 

; read and print successive buffers 

018a cdclBl call setup ;set up input file 

Oied feff cpi 255 ;2S5 if file not present 

010f c21b81 jnz openok ;skip if open is ok 

• file not there, give error message and return 

8112 1 If 301 lxi d,opnmsg 

8115 Cd9c81 call err 

8118 C3S101 jmp finis ; to return 

openok: ;open operation ok, set buffer index to end 

011b 3e80 mvi a,80h 

eild 321302 sta ibp ;set buffer pointer to 88h 

; hi contains next address to print 

0128 210000 lxi h,0 ;start with 0000 

gloop: 

0123 e5 push h ;save line position 

0124 cda201 call gnb 

0127 el pop h jrecall line position 

0128 da5101 jc finis ,-carry set by gnb if end file 
012b 4 7 mov b,a 

; print hex values 

; check for line fold 

012c 7d mov a,l 

012d e60£ ani 0£h ;check low 4 bits 

012£ C24401 jnz nonum 

; print line number 

0132 cd7201 call crl£ 

; check for break key 

0135 cd5901 call break 

; accum lsb = 1 if character ready 
; into carry 
;don't print any more 



; to next line number 



finis: 

; end of dump, return to ccp 

; (note that a jmp to 0000h reboots) 

0151 cd7201 call crlf 

0154 2al502 lhld oldsp 

0157 f9 sphl 

: stack pointer contains ccp's stack location 

0158 c9 ret ;to the ccp 



; subroutines 

break: ;check break key (actually any key will do) 

0159 e5d5c5 push h! push d! push b; environment saved 

015c 0e0b mvi c,brkf 

015e cdB580 call bdos 

0161 cldlel pop bl pop d! pop h; environment restored 

0164 c9 ret 

pchar: ;print a character 
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0138 


0f 


rrc 




0139 


da5101 


jc 


finis 


013c 


7c 


mov 


a,h 


013d 


cd8£01 


call 


phex 


0140 


7d 


mov 


a.l 


0141 


Cd8f01 

nonum: 


call 


phex 


0144 


23 


inx 


h 


0145 


Je2B 


mvi 


a, ' ' 


0147 


cd6501 


call 


pchar 


014a 


78 


mov 


a,b 


014b 


Cd8f01 


call 


phex 


014e 


C32301 


jmp 


gloop 



8165 e5d5c5 
9168 0e02 
916a 5f 
916b cd0500 
916e cldlel 
9171 c9 



push h! push d! push b; saved 

mvi c,typef 

mov e , a 

call bdos 

pop b! pop d! pop h; restored 

ret 



crlf: 



9172 3e0d 
)174 cd6501 
9177 3e0a 
9179 cd6501 
)17c c9 



mvi 

call 

mvi 

call 

ret 



a,cr 
pchar 
a, If 
pchar 



917d e60£ 
917f fe0a 
9181 d28901 

9184 c630 
9186 c38b01 



pnib: ;print nibble in reg a 

ani 0£h ;low 4 bits 

cpi 10 

jnc pl0 

less than or equal to 9 

adi ' ' 



0189 c637 pl0: 
018b cd6501 prn: 
018e c9 



]mp 



prn 



greater or equal to 1G 

adi 'a' - 10 

call pchar 
ret 



018f f5 

0190 0f 

0191 0£ 

0192 0£ 

0193 0f 

0194 Cd7d01 

0197 fl 

0198 cd7d01 
019b c9 



phex : 



;pr int 


hex char 


in reg 


a 


push 


psw 






rrc 








r re 








rrc 








rrc 








call 


pnib 


;pr int 


n 


pop 


psw 






call 


pnib 






ret 









019c 0e09 
019e cd050B 
01al c9 



;print error message 

d,e addresses message ending with "$'■ 

mvi cprintf ,-print buffer function 

call bdos 

ret 



gnb: ;get next byte 
01a2 3al302 Ida ibp 

1a5 fe80 cpi 80h 

01a7 c2b301 jnz g0 

read another buffer 



91aa cdce01 

91ad b7 

91ae cab301 

91bl 3 7 

91b2 c9 



call diskr 

ora a ;zero value if read ok 

jz g0 ;for another byte 

end of data, return with carry set for eof 

stc 

ret 



91b3 5f 

91b4 1600 

91b6 3c 

91b7 321302 



91ba 218000 
91bd 19 



01be 7e 



gf: ;read the byte at buff+reg a 

mov e,a ;ls byte of buffer index 

mvi d,0 ;double precision index to de 

inr a ; index=index+l 

sta ibp ;back to memory 

pointer is incremented 

save the current file address 

lxi h.buff 

dad d 

absolute character address is in hi 

mov a,m 
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; byte is in the accumulator 

01bf b7 ora a ;reset carry bit 

01c0 c9 ret 

setup: ; set up f ile 

; open the file for input 

01cl af xra a ;zero to accum 

01c2 327c00 sta fcbcr ;clear current record 

01c5 115c00 ' lxi d,£cb 

01c8 0e0£ mvi c,openf 

01ca cd0500 call bdos 

; 255 in accum if open error 

01cd c9 ret 

diskr: ;read disk file record 

Ice e5d5c5 push h! push d! push b 

01dl 115c00 lxi d.fcb 

01d4 0el4 mvi c.readf 

01d6 cd0500 call bdos 

ld9 cldlel pop b! pop ; ! pop h 

01dc c9 ret 

; fixed message area 

01dd 46494c0signon: db 'file du p version 2.0$' 

01f3 0d0a4e0opnmsg : db cr,lf,'no input file present on diskS' 

; variable area 

0213 ibp: ds 2 ; input buffer pointer 

0215 oldsp: ds 2 ;entry sp value from ccp 

; stackarea 

0217 ds 64 ;reserve 32 level stack 

stktop: 

0257 end 

Sample Random Access Program. 

This manual is concluded with a rather extensive, but complete example of 
random access operation. The program listed below performs the simple 
function of reading or writing random records upon command from the 
terminal. Given that the program has been created, assembled, and placed 
into a file labelled RANDOM.COM, the CCP level command: 

RANDOM X.DAT 

starts the test program. The program looks for a file by the name X.DAT (in 
this particular case) and, if found, proceeds to prompt the console for input. 
If not found, the file is created before the prompt is given. Each prompt takes 
the form 

next command? 

and is followed by operator input, terminated by a carriage return. The input 
commands take the form 

nW nR Q 
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where n is an integer value in the range to 65535, and W, R, and Q are simple 
command characters corresponding to random write, random read, and quit 
processing, respectively. If the W command is issued, the RANDOM 
program issues the prompt 

type data: 

The operator then responds by typing up to 127 characters, followed by a 
carriage return. RANDOM then writes the character string into the X.D AT 
file at record n. If the R command is issued, RANDOM reads record number 
n and displays the string value at the console. If the Q command is issued, the 
X.DAT file is closed, and the program returns to the console command 
processor. In the interest of brevity, the only error message is 

error, try again 

The program begins with an initialization section where the input file is 
opened or created, followed by a continuous loop at the label "ready" where 
the individual commands are interpreted. The default file control block at 
005CH and the default buffer at 0080H are used in all disk operations. The 
utility subroutines then follow, which contain the principal input line 
processor, called "readc." This particular program shows the elements of 
random access processing, and can be used as the basis for further program 
development. 

;*************************************************,>,> 

;* * 

;* sample random access program for cp/m 2.0 * 
; * • 

.******************************** ******************* 

0100 org. 100h ;base of tpa 

0000 = reboot equ 0000h ;system reboot 
0005 = bdos equ 0005h ;bdos entry point 

0001 = coninp equ 1 ;console input function 

0002 = conout equ 2 ;console output function 

0009 = pstring equ 9 ;print string until '$' 
000a = rstring equ 10 ;read console buffer 
000c = version equ 12 ;return version number 
000f - openf equ 15 ;file open function 

0010 = closef equ 16 ,-close function 
0016 = makef equ 22 ;make file function 

0021 - readr equ 33 ;read random 

0022 - writer equ 34 ;write random 

005c = fcb equ 005ch ;default file control block 

007d = ranrec equ fcb+33 ;random record position 

007f = ranovf equ fcb+35 ;high order (overflow) byte 

0080 = buff equ 0080h .-buffer address 

000d = cr equ 0dh ;carriage return 
000a = If equ 0ah ;line feed 

* • 

* load SP, set-up file for random access * 



************** 
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0100 31bc0 lxi sp, stack 

; version 2.0? 

0103 060c mvi c, version 

0105 cd050 call bdos 

0108 fe20 cpi 20h ;version 2.0 or better? 

010a d2160 jnc versok 

• bad version, message and go back 
010d lllbB lxi d.badver 

0110 cdda0 call print 

0113 C3000 jmp reboot 

versok : 

; correct version for random access 

0116 0e0f mvi copenf ;open deEault fcb 

0118 115c0 lxi d,£cb 

011b cd050 call bdos 

Bile 3c inr a ;err 255 becomes zero 

011£ c2370 jnz ready 

• cannot open file, so create it 
0122 0el6 mvi cmakef 

0124 Il5c0 lxi d,£cb 

0127 cd050 call bdos 

012a 3c inr a ;err 255 becomes zero 

012b c2370 jnz ready 

; cannot create file, directory full 

012e 113a0 lxi d.nospace 

0131 cdda0 call print 

■0134 C3000 jmp reboot (back to ccp 

.♦a************************************************' 
'. • ' 

j* loop back to "ready" after each command ' 

( 

ready : 

; file is ready for processing 

0137 cde50 call readcom jread next command 

013a 227d0 shld ranrec ,-store input record! 

013d 217£0 lxi h.ranovf 

0140 3600 mvi m,0 ;clear high byte if set 

8142 £e51 cpi 'Q' ;quit? 

144 C2560 jnz notq 

; quit processing, close file 

0147 Uelfl mvi c.closef 

0149 115cG lxi d,fcb 
014c cd050 call bdos 

014f 3c inr a ,-err 255 becomes 

0150 cab90 jz error ;error message, retry 
0153 c30l)0 jmp reboot ;back to ccp 

. * 

;* end of quit command, process write 

. * 

.ft************************************************* 

notq: 

; not the quit command, random write? 

0156 £e57 cpi 'W 

158 c2890 jnz notw 

; this is a random write, fill buffer until cr 

015b 114d0 lxi d.datmsg 

015e cdda0 call print ;data prompt 

0161 0e7f mvi c,127 ;up to 127 characters 

0163 21800 lxi h.buff {destination 
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8166 c5 

8167 e5 
0168 cdc28 
016b el 
816c cl 
B16d feBd 
816f ca788 

8172 77 

8173 23 

8174 0d 

8175 C266B 



cloop: ;read next character to buff 
;save counter 
;next destination 
;character to a 
; restore counter 
; restore next to f 
;end of line? 



erloop: 



push 


b 


push 


h 


call 


qe tchr 


pop 


h 


pop 


b 


cpi 


cr 


jz 


er loop 


not end 


, store 


mov 


in, a 


inx 


h 


dcr 


c 


jnz. 


rloop 



;next to fill 
;counter goes down 
;end of buffer? 



0178 3600 



end of read loop, store 00 
mvi m,0 



017a 0e22 

017c 115c0 

017f cd050 

0182 b7 

0183 c2b90 
0186 c3370 



write the record to selected record number 



:error code zero? 
■message if not 
for another record 



mvi 


c, wr iter 


lxi 


d,fcb 


call 


bdos 


ora 


a 


}nz 


er ror 


;jmp 


ready 



***************** 



end of write command, process read 



********************** 



8189 fe52 
816b c2b98 



not a write command, read record? 

cpi 'R' 

jnz error ;skip if not 



818e 8e21 
8198 115c8 
8193 Cd858 
8196 b7 
0197 C2b98 



read random record 



mvi 

lxi 

call 

ora 

jnz 



c, readr 

d,fcb 

bdos 

a 

error 



;return code 88? 



819a cdcfB 
819d 8e8B 
819f 21888 

Bla2 7e 

8 la 3 2 3 

01a4 e67f 

Bla6 ca378 

81a9 c5 

81aa e5 

Blab fe28 

81ad d4c80 

81b0 el 

Blbl cl 

Blb2 0d 

81b3 c2a20 

81b6 C337B 



wloop: 



read was successful, write to console 
call crlf ;new line 
mvi c,128 ;max 128 characters 
lxi h,buff ;next to get 



;next character 

;next to get 

;mask parity 

; for another command if 

;save counter 

;save next to get 

; graphic? 

;skip output if not 



;count=count-l 



mov 


a , m 


inx 


h 


ani 


7fh 


jz 


ready 


push 


b 


push 


h 


cpi 


■ ■ 


cnc 


putchr 


pop 


h 


pop 


b 


dcr 


c 


jnz 


wloop 


jmp 


ready 



* end of read command, all errors end-up here 

* 

********************************************** 



error: 

01b9 11590 lxi d,errmsg 

01bc cdda0 call print 

01bf C3370 jmp ready 
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81c2 
01c4 

eic7 



0e01 

cd850 

c9 



************ 



******************************* 



* utility subroutines for console i/o 



*********** 
getchr : 



*************************** 



;read next console character to a 

mvi c,coninp 

call bdos 
ret 



ales 

aica 
Bleb 
Bice 



putchr : 



0e02 
5f 

cdB5B 
c9 



;write character from a to console 

mvi cconout 

mov e,a ;character to send 

call bdos ;send character 

ret 



crlf : 



Blcf 
Bldl 
Bld4 
Bld6 
01d9 



3eBd 

cdc80 

3e0a 

cdc80 

c9 



;send carriage return line feed 

mvi a,cr ;carriage return 

call putchr 

mvi a , If ; 1 ine feed 

call putchr 

ret 



pr int: 



Ida 


d5 


push 


ldb 


edef 


call 


lde 


dl 


pop 


ldf 


0e09 


mvi 


lei 


cd050 


call 


le4 


c9 

readcom 


ret 
; read 


le5 


116b0 


lxi 


le8 


cdda0 


call 


leb 


0e0a 


mvi 


led 


117a0 


lxi 


lfa 


cd050 


call 
comma 


lf3 


21000 


lxi 


lf6 


117C0 


lxi 


lf9 


la readc: 


ldax 


lfa 


13 


inx 


lfb 


b7 


ora 


lfc 


c8 


rz 

not. z 


lfd 


d630 


sui 


Iff 


feBa 


cpi 


201 


d2130 


jnc 
add-i 


204 


29 


dad 


20S 


4d 


mov 


206 


44 


mov 


207 


29 


dad 


208 


29 


dad 


209 


09 


dad 


20a 


85 


add 


20b 


6f 


mov 


20c 


d2f90 


jnc 


20f 


24 


inr 


210 


C3f90 

endrd: 


jmp 
end o 


213 


C630 


adi 


215 


fe61 


cpi 



;print the buffer addressed by de until $ 
d 

crlf 

d ; new line 
c , p s t r i ng 
bdos ;print the string 



the next command line to the conbuf 
d .prompt 

print ;command? 
c , r s t r i ng 
d, conbuf 

bdos ; read command 1 i ne 
nd line is present, scan it 

h,0 ;start with 0000 

d , conl in; command 1 ine 

d ;next command character 

d ; to next command position 

a ;cannot be end of command 

ero, numeric? 

'0' 

10 ;carry if numeric 

endrd 
n next digit 



h 


;*2 


c,l 
b,h 
h 


;bc = value * 2 
;*4 


h 
b 


;*8 

;*2 + *8 = *10 


1 
l,a 


;+digit 


readc 


;for another char 


h 
readc 


; over flow 

;for another char 



f read, restore value in a 
'0' ; command 
'a' ;translate case? 
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8217 d8 



0218 e65f 
021a c9 



*************** 

badver : 
021b 536f79 db 

nospace: 
023a 4e6f29 db 

datmsg : 
024d 547970 db 

er rmsg : 
0259 457272 db 

prompt: 
026b 4e6570 db 



******* 



re 

lower case, mask lower case bits 

ani 10151111b 

ret 

r************»**************************»*«****** 

string data area for console messages 

******************************* 



'sorry, you need cp/m version 25' 
'no directory spaces' 
'type data: 5' 
'error, try again. $' 
'next command? 5' 



*********************** 



********** 



* fixed and variable data area 



2 7a 21 
027b 
2 7c 
0021 * 

029c 

2bc 



************ 
conbuf: db 
consiz: ds 
conlin: ds 
conlen equ 



•A**********************************, 
conlen (length of console buffer 
1 (resulting size after read 

32 (length 32 buffer 

S-consiz 



stack : 



ds 
end 



32 



(16 level stack 



Again, major improvements could be made to this particular program to 
enhance its operation. In fact, with some work, this program could evolve 
into a simple data base management system. One could, for example, assume 
a standard record size of 128 bytes, consisting of arbitrary fields within the 
record. A program, called GETKEY, could be developed which first reads a 
sequential file and extracts a specific field defined by the operator. For 
example, the command 

GETKEY NAMES.DAT LASTNAME 10 20 



would cause GETKEY to read the data base file NAMES.DAT and extract 
the "LASTNAME" field from each record, starting at position 10 and ending 
at character 20. GETKEY builds a table in memory consisting of each 
particular LASTNAME field, along with its 16-bit record number location 
within the file. The GETKEY program then sorts this list, and writes a new 
file, called LASTNAME.KE Y, which is an alphabetical list of LASTNAME 
fields with their corresponding record numbers. (This list is called an 
"inverted index" in information retrieval parlance.) 

Rename the program shown above as QUERY, and massage it a bit so that 
it reads a sorted key file into memory. The command line might appear as: 

QUERY NAMES.DAT LASTNAME.KEY 
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Instead of reading a number, the QUERY program reads an alphanumeric 
string which is a particular key to find in the NAMES.DAT data base. Since 
the LASTNAME.KEY list is sorted, you can find a particular entry quite 
rapidly by performing a "binary search" similar to looking up a name in the 
telephone book. That is, starting at both ends of the list, you examine the 
entry halfway in between and, if not matched, split either the upper half or 
the lower half for the next search. You'll quickly reach the item you're 
looking for (in log2(n) steps) where you'll find the corresponding record 
number. Fetch and display this record at the console, just as we have done in 
the program shown above. 

At this point you're just getting started. With a little more work, you can 
allow a fixed grouping size which differs from the 128 byte record shown 
above. This is accomplished by keeping track of the record number as well as 
the byte offset within the record. Knowing the group size, you randomly 
access the record containing the proper group, offset to the beginning of the 
group within the record read sequentially until the group size has been 
exhausted. 

Finally, you can improve QUERY considerably by allowing boolean 
expressions which compute the set of records which satisfy several 
relationships, such as a LASTNAME between HARDY and LAUREL, and 
an AGE less than 45. Display all the records which fit this description. 
Finally, if your lists are getting too big to fit into memory, randomly access 
your key files from the disk as well. One note of consolation after all this 
work: if you make it through the project, you'll have no more need for this 
manual! 
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System Function Summary 



FUNC FUNCTION NAME 



INPUT OUTPUT 

PARAMETERS RESULTS 






System Reset 


none 


none 


1 


Console Input 


none 


A = char 


2 


Console Output 


E = char 


none 


3 


Reader Input 


none 


A = char 


4 


Punch Output 


E = char 


none 


5 


List Output 


E = char 


none 


6 


Direct Console I/O 


see def 


see def 


7 


Get I/O Byte 


none 


A = IOBYTE 


8 


Set I/O Byte 


E = IOBYTE 


none 


9 


Print String 


DE = . Buffer 


none 


10 


Read Console Buffer 


DE = .Buffer 


see def 


11 


Get Console Status 


none 


A = 00/FF 


12 


Return Version Number 


none 


HL = Version* 


13 


Reset Disk System 


none 


see def 


14 


Select Disk 


E = Disk Number 


see def 


15 


Open File 


DE = .FCB 


A = Dir Code 


16 


Close File 


DE = .FCB 


A = Dir Code 


17 


Search for First 


DE = .FCB 


A = Dir Code 


18 


Search for Next 


none 


A = Dir Code 


19 


Delete File 


DE = .FCB 


A = Dir Code 


20 


Read Sequential 


DE = .FCB 


A = Err Code 


21 


Write Sequential 


DE = .FCB 


A = Err Code 


22 


Make File 


DE = .FCB 


A = Dir Code 


23 


Rename File 


DE = .FCB 


A = Dir Code 


24 


Return Login Vector 


none 


HL = Login Vect* 


25 


Return Current Disk 


none 


A = Cur Disk* 


26 


Set DMA Address 


DE = .DMA 


none 


27 


Get Addr( Alloc) 


none 


HL = . Alloc 


28 


Write Protect Disk 


none 


see def 


29 


Get R/O Vector 


none 


HL = R/O Vect* 


30 


Set File Attributes 


DE = .FCB 


see def 


31 


Get Addr (disk parms) 


none 


HL = .DPB 


32 


Set/Get User Code 


see def 


see def 


33 


Read Random 


DE = .FCB 


A = Err Code 


34 


Write Random 


DE = .FCB 


A = Err Code 


35 


Compute File Size 


DE = .FCB 


rO, rl, r2 


36 


Set Random Record 


DE = .FCB 


rO, rl, r2 



*Note that A = L, and B = H upon return 
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CHAPTER 3 
CP/M EDITOR 

Introduction to ED 

ED Operation 

Text Transfer Functions 

Memory Buffer Organization 

Memory Buffer Operation 

Command Strings 

Text Search and Alteration 

Source Libraries 

Repetitive Command Execution 

ED Error Conditions 

Summary of Control Characters 

Summary of ED Commands 

ED Text Editing Commands 
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Introduction to ED 

ED is the context editor for CP/M, and is used to create and alter CP/M 
source files. ED is initiated in CP/M by typing 

{(filename) | 

( 
( filename) •( filetype) ) 

In general, ED reads segments of the source file given by (filename) or 
(filename) • (filetype) into central memory, where the file is manipulated by 
the operator, and subsequently written back to disk after alterations. If the 
source file does not exist before editing, it is created by ED and initialized to 
empty. The overall operation of ED is shown in Figure 1. 

ED Operation 

ED operates upon the source file, denoted in Figure 1 by x.y, and passes all 
text through a memory buffer where the text can be viewed or altered (the 
number of lines which can be maintained in the memory buffer varies with 
the line length, but has a total capacity of about 6000 characters in a 16K 
CP/M system). Text material which has been edited is written onto a 
temporary work file under command of the operator. Upon termination of 
the edit, the memory buffer is written to the temporary file, followed by any 
remaining (unread) text in the source file. The name of the original file is 
changed from x.y to x.BAK so that the most recent previously edited source 
file can be reclaimed if necessary (see the CP/M commands ERASE and 
RENAME). The temporary file is changed from x.$$$ to x.y which becomes 
the resulting edited file. 

The memory buffer is logically between the source file and working file as 
shown in Figure 2. 

Text Transfer Functions 

Given that n is an integer value in the range through 65535, the following 
ED commands transfer lines of text from the source file through the memory 
buffer to the temporary (and eventually final) file: 
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Figure 1. Overall ED Operation 





Append 
(A)' 



Source 
Libraries 



(R) 



I 

After | , . 
Edit I lE) 
I 



Write 



Memory Buffer 



(E) 




Insert 
(I) 



Type 
,, (T) 



Note: the ED program accepts both lower and upper case ASCII characters 
asinput from the console. Single letter commands can be typed in either case. 
The U command can be issued to cause ED to translate lower case 
alphabetics to upper case as characters are filled to the memory buffer from 
the console. Characters are echoed as typed without translation, however. 
The -U command causes ED to revert to "no translation" mode. ED starts 
with an assumed -U in effect. 
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Figure 2. Memory Buffer Organization 
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Figure 3. Logical Organization of Memory Buffer 



Memory Buffer 



first <cr><lf> 

line 

<cr><lf> 

current A 

line CL j£± 

last <cr><lf> 

line 



<cr><lf> 
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nA(cr) * Append the next n unprocessed source lines from the source 
file at SP to the end of the memory buffer at MP. Increment 
SP and MP by n. 

nW(cr) Write the first n lines of the memory buffer to the temporary 
file free space. Shift the remaining lines n + 1 through MP to 
the top of the memory buffer. Increment TP by n. 

E<cr) End the edit. Copy all buffered text to temporary file, and 

copy all unprocessed source lines to the temporary file. 
Rename files as described previously. 

H(cr) Move to head of new file by performing automatic E 

command. Temporary file becomes the new source file, the 
memory buffer is emptied, and a new temporary file is created 
(equivalent to issuing an E command, followed by a 
reinvocation of ED using x.y as the file to edit). 

0(cr) Return to original file. The memory buffer is emptied, the 

temporary file is deleted, and the SP is returned to position 1 
of the source file. The effects of the previous editing 
commands are thus nullified. 

Q(cr) Quit edit with no file alterations, return to CP/M. 

There are a number of special cases to consider. If the integer n is omitted in 
any ED command where an integer is allowed, then 1 is assumed. Thus, the 
commands A and W append one line and write 1 line, respectively. In 
addition, if a pound sign ( # ) is given in the place of n, then the integer 66535 
is assumed (the largest value for n which is allowed). Since most reasonably 
sized source files can be contained entirely in the memory buffer, the 
command # A is often issued at the beginning of the edit to read the entire 
source file to memory. Similarly, the command # W writes the entire buffer 
to the temporary file. Two special forms of the A and W commands are 
provided as a convenience. The command OA fills the current memory buffer 
to at least half-full, while OW writes lines until the buffer is at least half 
empty. It should also be noted that an error is issued if the memory buffer size 
is exceded. The operator may then enter any command (such as W) which 
does not increase memory requirements. The remainder of any partial line 
read during the overflow will be brought into memory on the next successful 
append. 



*<er) represents the carriage-return key 
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Memory Buffer Organization 

The memory buffer can be considered a sequence of source lines brought in 
with the A command from a source file. The memory buffer has an associated 
(imaginary) character pointer (CP) which moves throughout the memory 
buffer under command of the operator. The memory buffer appears logically 
as shown in Figure 3 where the dashes represent characters of the source line 
of indefinite length, terminated by carriage return (<cr> ) and line feed «lf) ) 
characters, and c ^j represents the imaginary character pointer. Note that the 
CP is always located ahead of the first character of the first line, behind the 
last character of the last line, or between two characters. The current line CL 
is the source line which contains the CP. 

Memory Buffer Operation 

Upon initiation of ED, the memory buffer is empty (i.e., CP is both ahead and 
behind the first and last character). The operator may either append lines (A 
command) from the source file, or enter the lines directly from the console 
with the insert command 

I<cr> 

ED then accepts any number of input lines, where each line terminates with 
a (cr> (the <lf) is supplied automatically), until a control-z (denoted by tz) 
is typed by the operator. The CP is positioned after the last character 
entered. The sequence 

I<cr> 

NOW IS THE<cr> 

TIME FOR<cr> 

ALL GOOD MEN<cr> 

Tz 

leaves the memory buffer as shown below 

NOWISTHE<cr><lf> 

TIME FOR<cr><lf> 

ALL GOOD MEN<cr><lf>ct 

Various commands can then be issued which manipulate the CP or display 
source text in the vicinity of the CP. The commands shown below with a 
preceding n indicate that an optional unsigned value can be specified. When 
preceded by ± , the command can be unsigned, or have an optional preceding 
plus or minus sign. As before, the pound sign ( # ) is replaced by 65535. If an 
integer n is optional, but not supplied, then n = 1 is assumed. Finally, if a plus 
sign is optional, but none is specified, then + is assumed. 
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±B(cr) move CP to beginning of memory buffer if +, and to bottom 
if-. 

± nC(cr) move CP by ± n characters (toward front of buffer if + ), 
counting the (cr)(lf) as two distinct characters. 

± nD(cr) delete n characters ahead of CP if plus and behind CP if 
minus. 

±nK(cr) kill (i.e. remove) ±n lines of source text using CP as the 
current reference. If CP is not at the beginning of the current 
line when K is issued, then the characters before CP remain 
if + is specified, while the characters after CP remain if - is 
given in the command. 

± nL(cr) if n = 0, move CP to the beginning of the current line (if it is 
notalready there). If n ^0, first move the CP to the beginning 
of the current line, and then move it to the beginning of the 
line which is n lines down (if + ) or up (if-). The CP will stop 
at the top or bottom of the memory buffer if too large a value 
is specified. 

± nT(cr) If n = then type the contents of the current line up to CP. If 
n = 1 then type the contents of the current line from CP to the 
end of the line. If n > 1 then type the current line along with 
n-1 lines which follow, if + is specified. Similarly, if n> land 
- is given, type the previous n lines, up to the CP. The break 
key can be depressed to abort long type-outs. 

± n(cr) equivalent to ± nLT, which moves up or down and types a 
single line. 



Command Strings 



Any number of commands can be typed contiguously (up to the capacity of 
the CP/M console buffer), and are executed only after the (cr) is typed. 
Thus, the operator may use the CP/M console command functions to 
manipulate the input command. 

Rubout remove the last character 

Control-X delete the entire line 

Control-C re-initialize the CP/M System 
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Control-E return carriage for long lines without transmitting buffer 
(max 128 chars) 

Suppose the memory buffer contains the characters shown in the previous 
section, with the CP following the last character of the buffer. The command 
strings shown below produce the results shown to the right. 



Command String 



Effect 



Resulting Memory Buffer 



B2T(cr) move to beginning of 

buffer and type 2 lines: 
"NOW IS THE 
TIME FOR" 



cp 



NOWISTHE<cr)<lf> 
TIMEFOR<cr)<lf> 
ALL GOOD MEN<cr)<lf> 



5C0T<cr> move CP 5 characters and 

type the beginning of the 
line "NOW I" 



NOWIASTHE<cr)<lf> 



2L-T(cr) move two lines down and 

type previous line 
"TIME FOR" 

-L#K(cr) move up one line, delete 

65535 lines which follow 



cp 



NOWISTHE<cr)<lf> 
TIMEFOR<cr)<lf> 
ALL GOOD MEN<cr)<lf> 



NOWISTHE<cr)<lf> 



cp 



I<cr> 

TIME TO<cr> 

INSERT(cr) 

Tz 

-2L#T<cr> 



insert two lines 
of text 



NOWISTHE<cr)<lf> 

TIMETO<cr><lf> 

INSERT<cr><lf>A 



move up two lines, and type NOW IS THE<cr><lf>* 
65535 lines ahead of CP TIME TO<cr><lf> 
"NOW IS THE" INSERT<cr><lf) 



<cr> 



move down one line 
and type one line 
"INSERT" 



NOWISTHE<cr)<lf> 
TIME TO<cr><lf> * 
INSERT <cr)<lf> 
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Text Search and Alteration 

ED also has a command which locates strings within the memory buffer. The 
command takes the form 



nF C!C 2 



-m 



where q through c k represent the characters to match followed by either a 
<cr) or control -z.* ED starts at the current position of CP and attempts to 
match all k characters. The match is attempted n times, and if successful, the 
CP is moved directly after the character c k . If the n matches are not 
successful, the CP is not moved from its initial position. Search strings can 
include tl (control-1), which is replaced by the pair of symbols <cr) (If). 

The following commands illustrate the use of the F command: 

Command String Effect Resulting Memory Buffer 

B#T(cr) move to beginning * NOW IS THE (cr)(lf> 

and type entire TIME FOR(cr) (If) 

buffer ALL GOOD MEN(cr) (If) 

FS T(cr) find the end of NOW IS T *HE(cr) (If) 

the string "S T" 

FITzOTT find the next "I" and type NOW IS THE(cr)(lf) 

to the CP then type the TI^ME FOR(cr)(lf) 

remainder of the current ALL GOOD MEN(cr)(lf) 
line: "TIME FOR" 

An abbreviated form of the insert command is also allowed, which is often 
used in conjunction with the F command to make simple textual changes. 
The form is: 

Ic 1 C2...c n Tz or 
I C!C 2 . . . c„(cr) 

where cj through c n are characters to insert. If the insertion string is 
terminated by a Tz, the characters Cj through c n are inserted directly 
following the CP, and the CP is moved directly after character c n . The action 
is the same if the command is followed by a (cr) except that a (cr)(lf) is 
automatically inserted into the text following character c„. Consider the 
following command sequences as examples of the F and I commands: 



•The control-z is used if additional commands will be typed following the Tz. 
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Command String 



Effect 



BITHIS IS T z<cr> 

Insert "THIS IS" 
at the beginning 
of the text 



Resulting Memory Buffer 

THIS IS*NOW THE<cr><If> 
TIME FOR <cr><lf> 
ALL GOOD MEN<cr>(lf) 



FTIME Tz-4DIPLACE T z<cr> 

find "TIME" and delete 
it; then insert "PLACE" 



THIS IS NOW THE<cr)<lf> 
PLACE *FOR<cr)<lf> 
ALL GOOD MEN<cr)<lf> 



3FOTz-3D5DICHANGEST<cr> THIS IS NOW THE<cr><lf> 

find third occurrence of PLACE FOR<cr><lf> 
"O" (i.e. the second "O" in ALL CHANGES * <cr> ( lf> 
GOOD), deiete previous 3 
characters; then insert 
"CHANGES" 



-8CISOURCE<cr> 

move back 8 characters 
and insert the line 
"SOURCE<cr><lf>" 



THIS IS NOW THE<cr)<lf> 
PLACE FOR<cr)<lf> 
ALLSOURCE<cr)<lf> 
*CHANGES<cr>(lf) 



ED also provides a single command which combines the F and I commands 
to perform simple string substitutions. The command takes the form 

nSc^. ..CkTzd^.. .<!,„ < tz > 

and has exactly the same effect as applying the command string 
F Cl c 2 . . . c k T z -kDId 1 d 2 • • ■ dm j ^H 

a total of n times. That is, ED searches the memory buffer starting at the 
current position of CP and successively substitutes the second string for the 
first string until the end of buffer, or until the substitution has been 
performed n times. 

As a convenience, a command similar to F is provided by ED which 
automatically appends and writes fines as the search proceeds. The form is 

nNc 1 c 2 ...c k | ( " ) | 
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which searches the entire source file for the nth occurrence of the string c : c 2 
. . . c k (recall that F fails if the string cannot be found in the current buffer). 
The operation of the N command is precisely the same as F except in the case 
that the string cannot be found within the current memory buffer. In this 
case, theentire memory contents is written (i.e., an automatic # Wis issued). 
Input lines are then read until the buffer is at least half full, or the entire 
source file is exhausted. The search continues in this manner until the string 
has been found n times, or until the source file has been completely 
transferred to the temporary file. 

A final line editing function, called the juxtaposition command takes the 
form 

nJ Cl c 2 ...c k Tz dida-.-d^z e ie2 . . . e q j ^ 

with the following action applied n times to the memory buffer: search from 
the current CP for the next occurrence of the string c x c 2 . . . c k . If found, insert 
the string d b d 2 . . .,d m , and move CP to follow d m . Then delete all characters 
following CP up to (but not including) the string e 1; e 2> . . . e q , leaving CP 
directly after d m . If e b e e , . . . e q cannot be found, then no deletion is made. If 
the current line is 

* NOW IS THE TIME(cr)(lf) 

Then the command 

JWTzWHATTzTl(cr) 

Results in 

NOW WHAT c £ (cr)(lf> 

(Recall that Tl represents the pair (cr)(lf)in search and substitution 
strings). 

It should be noted that the number of characters allowed by ED in the F, S, 
N, and J commands is limited to 100 symbols. 



Source Libraries 

ED also allows the inclusion of source libraries during the editing process 
with the R command. The form of this command is 
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Rf!f 2 ..f n tz or 

Rf 1 f 2 ..f n <cr> 

where fif 2 . . f n is the name of a source file on the disk with an assumed filetype 
of 'LIB.' ED reads the specified file, and places the characters into the 
memory buffer after CP, in a manner similar to the I command. Thus, if the 
command 

RMACRO(cr) 

is issued by the operator, ED reads from the file MACRO. LIB until the 
end-of-file, and automatically inserts the characters into the memory buffer. 

Repetitive Command Execution 

The macro command M allows the ED user to group ED commands together 
for repeated evaluation. The M command takes the form: 

n M C!C 2 . . . c k <j (™) 

where CxC 2 . . . c^ represent a string of ED commands, not including another 
M command. ED executes the command string n times if n)l. If n = or 1, the 
command string is executed repetitively until an error condition is 
encountered (e.g., the end of the memory buffer is reached with an F 
command). 

As an example, the following macro changes all occurrences of GAMMA to 
DELTA within the current buffer, and types each line which is changed: 

MFGAMMATz-5DIDELTATzOTT<cr> 

or equivalently 

MSGAMMATzDELTATzOTT<cr) 



ED Error Conditions 

On error conditions, ED prints the last character read before the error, along 
with an error indicator: 

? unrecognized command 
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> memory buffer full (use one of the commands D, K, N, S, or 

W to remove characters), F, N, or S strings too long. 

# cannot apply command the number of times specified (e.g., in 
F command) 

O cannot open LIB file in R command 

Cyclic redundancy check (CRC) information is written with each output 
record under CP/M in order to detect errors on subsequent read operations. 
If a CRC error is detected, CP/M will type 

PERM ERR DISK d 

where d is the currently selected drive (A, B, . . .). The operator can choose 
to ignore the error by typing any character at the console (in this case, the 
memory buffer data should be examined to see if it was incorrectly read), or 
the user can reset the system and reclaim the backup file, if it exists. The file 
can be reclaimed by first typing the contents of the BAK file to ensure that 
it contains the proper information: 

TYPE x.BAK(cr) 

where x is the file being edited. Then remove the primary file: 

ERA x.y<cr) 

and rename the BAK file: 

RENx.y = x.BAK<cr) 

The file can then be re-edited, starting with the previous version. 

Summary of Control Characters 

The following table summarizes the Control characters and commands 
available in ED: 

Control Character Function 

Tc system reboot 

Te physical <cr)<lf) (not actually entered in 

command) 
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Ti logical tab (cols 1, 8, 15, ... ) 

Tl logical (cr){lf) in search and substitute strings 

Tx line delete 

Tz string terminator 

rubout character delete 

break discontinue command (e.g., stop typing) 

Summary of ED Commands 

Command Function 

nA append lines 

± B begin bottom of buffer 

± nC move character positions 

± nD delete characters 

E end edit and close files (normal end) 

nF find string 

H end edit, close and reopen files 

I insert characters 

nJ place strings in juxtaposition 

± nK kill lines 

± nL move down/up lines 

nM macro definition 

nN find next occurrence with autoscan 
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return to original file 


±nP 


move and print pages 


Q 


quit with no file changes 


R 


read library file 


nS 


substitute strings 


±nT 


type lines 


_U 


translate lower to upper 
-U 


nW 


write lines 


nZ 


sleep 


n(cr> 


move and type ( ± nLT) 



ED Text Editing Commands 

The ED context editor contains a number of commands which enhance its 
usefulness in text editing. The improvements are found in the addition of line 
numbers, free space interrogation, and improved error reporting. 

The context editor issued with CP/M produces absolute line number prefixes 
when the "V" (Verify Line Numbers) command is issued. Following the V 
command, the line number is displayed ahead of each line in the format: 



where nnnnn is an absolute line number in the range 1 to 65535. If the 
memory buffer is empty, or if the current line is at the end of the memory 
buffer, then nnnnn appears as 5 blanks. 

The user may reference an absolute line number by preceding any command 
by a number followed by a colon, in the same format as the line number 
display. In this case, the ED program moves the current line reference to the 
absolute line number, if the line exists in the current memory buffer. Thus 
the command 
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345 :T 

is interpreted as "move to absolute line 345, and type the line!' Note that 
absolute line numbers are produced only during the editing process, and are 
not recorded with the file. In particular, the line numbers will change 
following a deleted or expanded section of text. 

The user may also reference an absolute line number as a backward or 
forward distance from the current line by preceding the absolute line number 
by a colon. Thus, the command 

:400T 

is interpreted as "type from the current line number through the line whose 
absolute number is 400." Combining the two line reference forms, the 
command 

345::400T 

for example, is interpreted as "move to absolute line 345, then type through 
absolute line 400." Note that absolute line references of this sort can precede 
any of the standard ED commands. 

A special case of the V command, "0V" prints the memory buffer statistics 
in the form: 

free/total 

where "free" is the number of free bytes in the memory buffer (in decimal), 
and "total" is the size of the memory buffer. 

ED also includes a "block move" facility implemented through the "X" 
(Xfer) command. The form 

nX 

transfers the next n lines from the current line to a temporary file called 

X$$$$$$$.LIB 

which is active only during the editing process. In general, the user can 
reposition the current line reference to any portion of the source file and 
transfer lines to the temporary file. The transferred lines accumulate one 
after another in this file, and can be retrieved by simply typing: 
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R 

which is the trivial case of the library read command. In this case, the entire 
transferred set of lines is read into the memory buffer. Note that the X 
command does not remove the transferred lines from the memory buffer, 
although a K command can be used directly after the X, and the R command 
does not empty the transferred line file. That is, given that a set of lines has 
been transferred with the X command, they can be re-read any number of 
times back into the source file. The command 

OX 

is provided, however, to empty the transferred line file. 

Note that upon normal completion of the ED program through Q or E, the 
temporary LIB file is removed. If ED is aborted through Control-C, the LIB 
file will exist if lines have been transferred, but will generally be empty (a 
subsequent ED invocation will erase the temporary file). 

Due to common typographical errors, ED requires several potentially 
disastrous commands to be typed as single letters, rather than in composite 
commands. The commands 

E (end), H (head), O (original), Q (quit) 

must be typed as single letter commands. 

ED also prints error messages in the form 

BREAK "x" AT c 

where x is the error character, and c is the command where the error occurred. 
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Introduction 

The CP/M assembler reads assembly language source files from the diskette, 
and produces 8080 machine language in Intel hex format. The CP/M 
assembler is initiated by typing 

ASM filename 
or 

ASM filename. parms 

In both cases, the assembler assumes there is a file on the diskette with the 
name 

filename.ASM 

which contains an 8080 assembly language source file. The first and second 
forms shown above differ only in that the second form allows parameters to 
be passed to the assembler to control source file access and hex and print file 
destinations. 

In either case, the CP/M assembler loads, and prints the message 

CP/M ASSEMBLER VER n.n 

where n.n is the current version number. In the case of the first command, the 
assembler reads the source file with assumed file type "ASM" and creates two 
output files. 

filename. HEX 

and 

filename.PRN 

The "HEX" file contains the machine code corresponding to the original 
program in Intel hex format, and the "PRN" file contains an annotated 
listing showing generated machine code, error flags, and source lines. If errors 
occur during translation, they will be listed in the PRN file as well as at the 
console. 

The second command form can be used to redirect input and output files 
from their defaults. In this case, the "parms" portion of the command is a 
three letter group which specifies the origin of the source file, the destination 
of the hex file, and the destination of the print file. The form is 

filename.plp2p3 
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where pi, p2, and p3 are single letters 

pi: A,B, •« , Y designates the disk name which contains 
the source file 

p2: A,B, •••> Y designates the disk name which will receive 
the hex file 
Z skips the generation of the hex file 

p3: A,B» •», Y designates the disk name which will receive 
the print file 
X places the listing at the console 

Z skips generation of the print file 

Thus, the command 

ASM X.AAA 

indicates that the source file (X.ASM) is to be taken from disk A, and that 
the hex (X.HEX) and the print (X.PRN) files are to be created also on disk 
A. This form of the command is implied if the assembler is run from disk A. 
That is, given that the operator is currently addressing disk A, the above 
command is equivalent to 

ASMX 

The command 

ASM X.ABX 

indicates that the source file is to be taken from disk A, the hex file is placed 
on disk B, and the listing file is to be sent to the console. The command 

ASM X.BZZ 

takes the source file from disk B, and skips the generation of the hex and print 
files. (This command is useful for fast execution of the assembler to check 
program syntax.) 

The source program format is compatible with both the Intel 8080 assembler 
(macros are not currently implemented in the CP/M assembler, however), as 
well as the Processor Technology Software Package #1 assembler. That is, 
the CP/M assembler accepts source programs written in either format. 
There are certain extensions in the CP/M assembler which make it 
somewhat easier to use. These extensions are described below. 
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Program Format 

An assembly language program acceptable as input to the assembler consists 
of a sequence of statements of the form 

line# label operation operand ;comment 

where any or all of the fields may be present in a particular instance. Each 
assembly language statement is terminated with a carriage return and line 
feed (the line feed is inserted automatically by the ED program), or with the 
character "!" which is treated as an end-of-line by the assembler (thus, 
multiple assembly language statements can be written on the same physical 
line if separated by exclamation symbols). 

The line* is an optional decimal integer value representing the source 
program line number, which is allowed on any source line to maintain 
compatibility with the Processor Technology format. In general, these line 
numbers will be inserted if a line-oriented editor is used to construct the 
original program, and thus ASM ignores this field if present. 

The label field takes the form 

identifier 
or 

identifier: 

and is optional, except where noted in particular statement types. The 
identifier is a sequence of alphanumeric characters (alphabetics and 
numbers), where the first character is alphabetic. Identifiers can be freely 
used by the programmer to label elements such as program steps and 
assembler directives, but cannot exceed 16 characters in length. All 
characters are significant in an identifier, except for the embedded dollar 
symbol ($) which can be used to improve readability of the name. Further, all 
lower case alphabetics are treated as if they were upper case. Note that the 
":" following the identifier in a label is optional (to maintain compatibility 
between Intel and Processor Technology). Thus, the following are all valid 
instances of labels 

x x y long$name 

x- yxl: longer$named$data: 

X1Y2 Xlx2 x234$5678$9012$3456: 

The operation field contains either an assembler directive, or pseudo 
operation, or an 8080 machine operation code. The pseudo operations and 
machine operation codes are described below. 
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The operand field of the statement, in general, contains an expression formed 
out of constants and labels, along with arithmetic and logical operations on 
these elements. Again, the complete details of properly formed expressions 
are given below. 

The comment field contains arbitrary characters following the "■" symbol 
until the next real or logical end-of-line. These characters are read listed 
and otherwise ignored by the assembler. In order to maintain compatibility 
with the Processor Technology assembler, the CP/M assembler also treats 
statements which begin with a "*" in column one as comment statements 
which are listed and ignored in the assembly process. Note that the Processor 
Technology assembler has the side effect in its operation of ignoring the 
characters after the operand field has been scanned. This causes an 
ambiguous situation when attempting to be compatible with Intel's 
language, since arbitrary expressions are allowed in this case. Hence 
programs which use this side effect to introduce comments, must be edited 
to place a ";" before these fields in order to assemble correctly. 

The assembly language program is formulated as a sequence of statements 
of the above form, terminated optionally by an END statement All 
statements following the END are ignored by the assembler. 

Forming the Operand 

In order to completely describe the operation codes and pseudo operations 
it is necessary to first present the form of the operand field, since it is used in 
nearly all statements. Expressions in the operand field consist of simple 
operands (labels, constants, and reserved words), combined in properly 
formed subexpressions by arithmetic and logical operators. The expression 
computation is carried out by the assembler as the assembly proceeds Each 
expression must produce a 16-bit value during the assembly. Further, the 
number of significant digits in the result must not exceed the intended' use. 
That is if an expression is to be used in a byte move immediate instruction, 
then the most significant 8 bits of the expression must be zero. The 
restrictions on the expression significance are given with the individual 
instructions. 



Labels 

As discussed above, a label is an identifier which occurs on a particular 
statement. In general, the label is given a value determined by the type of 
statement which it precedes. If the label occurs on a statement which 
generates machine code or reserves memory space (e.g, a MOV instruction 
or a DS pseudo operation), then the label is given the value of the program 
address which it labels. If the label precedes an EQU or SET, then the label 
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is given the value which results from evaluating the operand field. Except for 
the SET statement, an identifier can label only one statement. 

When a label appears in the operand field, its value is substituted by the 
assembler. This value can then be combined with other operands and 
operators to form the operand field for a particular instruction. 



Numeric Constants 

A numeric constant is a 16-bit value in one of several bases. The base, called 
the radix of the constant, is denoted by a trailing radix indicator. The radix 
indicators are 

B binary constant (base 2) 

octal constant (base 8) 

Q octal constant (base 8) 

D decimal constant (base 10) 

H hexadecimal constant (base 16) 

Q is an alternate radix indicator for octal numbers since the letter O is easily 
confused with the digit 0. Any numeric constant which does not terminate 
with a radix indicator is assumed to be a decimal constant. 

A constant is thus composed as a sequence of digits, followed by an optional 
radix indicator, where the digits are in the appropriate range for the radix. 
That is binary constants must be composed of and 1 digits, octal constants 
can contain digits in the range 0-7, while decimal constants contain decimal 
digits. Hexadecimal constants contain decimal digits as well as hexadecimal 
digits A (10D), B (11D ), C (12D), D (13D), E (14D), and F (15D). Note that the 
leading digit of a hexadecimal constant must be a decimal digit in order to 
avoid confusing a hexadecimal constant with an identifier (a leading will 
always suffice). A constant composed in this manner must evaluate to a 
binary number which can be contained within a 16-bit counter, otherwise it 
is truncated on the right by the assembler. Similar to identifiers, imbedded 
"$" are allowed within constants to improve their readability. Finally, the 
radix indicator is translated to upper case if a lower case letter is 
encountered. The following are all valid instances of numeric constants 

1234 1234D 1100B 1111$0000$1111$0000B 
1234H OFFEH 33770 33$77$22Q 
3377o 0fe3h 1234d Offffh 
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Reserved Words 



There are several reserved character sequences which have predefined 
meanings in the operand field of a statement. The names of 8080 registers are 
given below, which, when encountered, produce the value shown to the right. 



A 


7 


B 





C 


1 


D 


2 


E 


3 


H 


4 


L 


5 


M 


6 


SP 


6 


PSW 


6 



(Again, lower case names have the same values as their upper case 
equivalents.) Machine instructions can also be used in the operand field, and 
evaluate to their internal codes. In the case of instructions which require 
operands, where the specific operand becomes a part of the binary bit pattern 
of the instruction (e.g, MOV A,B), the value of the instruction (in this case 
MOV) is the bit pattern of the instruction with zeroes in the optional fields 
(e.g, MOV produces 40H). 

When the symbol "$" occurs in the operand field (not imbedded within 
identifiers and numeric constants) its value becomes the address of the next 
instruction to generate, not including the instruction contained within the 
current logical line. 



String Constants 

String constants represent sequences of ASCII characters, and are 
represented by enclosing the characters within apostrophe symbols ('). All 
strings must be fully contained within the current physical line (thus 
allowing "!" symbols within strings), and must not exceed 64 characters in 
length. The apostrophe character itself can be included within a string by 
representing it as a double apostrophe (the two keystrokes " ), which becomes 
a single apostrophe when read by the assembler. In most cases, the string 
length is restricted to either one or two characters (the DB pseudo operation 
is an exception), in which case the string becomes an 8 or 16 bit value, 
respectively. Two character strings become a 16-bit constant, with the 
second character as the low order byte, and the first character as the high 
order byte. 
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The value of a character is its corresponding ASCII code. There is no case 
translation within strings, and thus both upper and lower case characters 
can be represented. Note however, that only graphic (printing) ASCII 
characters are allowed within strings. Valid strings are 

'A' AB' 'ab' 'c' 

a 

'Walla Walla Wash.' 
'She said "Hello" to me.' 
'I said "Hello" to her.' 



Arithmetic and Logical Operators 

The operands described above can be combined in normal algebraic notation 
using any combination of properly formed operands, operators, and 
parenthesized expressions. The operators recognized in the operand field are 

a + b unsigned arithmetic sum of a and b 

a - b unsigned arithmetic difference between a and b 

+ b unary plus (produces b) 

- b unary minus (identical to - b) 

a * b unsigned magnitude multiplication of a and b 

a / b unsigned magnitude division of a by b 

a MOD b remainder after a / b 

NOT b logical inverse of b (allO's become l's, 1'sbecomeO's), 

where b is considered a 16-bit value 
a AND b bit-by -bit logical and of a and b 

a OR b bit-by -bit logical or of a and b 

a XOR b bit-by-bit logical exclusive or of a and b 

a SHL b the value which results from shifting a to the left by 

an amount b, with zero fill 
a SHR b the value which results from shifting a to the right 

by an amount b, with zero fill 

In each case, a and b represent simple operands (labels, numeric constants, 
reserved words, and one or two character strings), or fully enclosed 
parenthesized subexpressions such as 

10 + 20 10h+37Q LI/ 3 (L2 + 4)SHR3 

('a' and 5fh) + '0' ('B' + B) OR (PSW + M) 

(l + (2 + c))shr(A-(B + l)) 

Note that all computations are performed at assembly time as 16-bit 
unsigned operations. Thus, -1 is computed as 0-1 which results in the value 
Offffh (i.e., all l's). The resulting expression must fit the operation code in 
which it is used. If, for example, the expression is used in a ADI (add 
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immediate) instruction, then the high order eight bits of the expression must 
be zero. As a result, the operation "ADI -1" produces an error message (-1 
becomes Offffh which cannot be represented as an 8 bit value), while "ADI 
(-1) AND OFFH" is accepted by the assembler since the "AND" operation 
zeroes the high order bits of the expression. 



Precedence of Operators 

As a convenience to the programmer, ASM assumes that operators have a 
relative precedence of application which allows the programmer to write 
expressions without nested levels of parentheses. The resulting expression 
has assumed parentheses which are defined by the relative precedence. The 
order of application of operators in unparenthesized expressions is listed 
below. Operators listed first have highest precedence (they are applied first 
in an unparenthesized expression), while operators listed last have lowest 
precedence. Operators listed on the same line have equal precedence, and are 
applied from left to right as they are encountered in an expression 

* / MOD SHL SHR 

- + 

NOT 

AND 

ORXOR 

Thus, the expressions shown to the left below are interpreted by the 
assembler as the fully parenthesized expressions shown to the right below 

a*b + c (a*b) + c 

a + b * c a + (b * c) 

aMODb'cSHLd ((a MOD b) * c) SHLd 

a OR b AND NOT c + d SHL e a OR (b AND (NOT (c + (d SHL e)))) 



Balanced parenthesized subexpressions can always be used to override the 
assumed parentheses, and thus the last expression above could be rewritten 
to force application of operators in a different order as 

(a OR b) AND (NOT c) + d SHL e 

resulting in the assumed parentheses 

(a OR b) AND ( (NOT c) + (d SHL e) ) 
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Note that an unparenthesized expression is well-formed only if the 
expression which results from inserting the assumed parentheses is 
well-formed. 

Assembler Directives 

Assembler directives are used to set labels to specific values during the 
assembly, perform conditional assembly, define storage areas, and specify 
starting addresses in the program. Each assembler directive is denoted by a 
"pseudo operation" which appears in the operation field of the line. The 
acceptable pseudo operations are 

ORG set the program or data origin 

END end program, optional start address 

EQU numeric "equate" 

SET numeric "set" 

IF begin conditional assembly 

ENDIF end of conditional assembly 

DB define data bytes 

DW define data words 

DS define data storage area 



The ORG Directive 

The ORG statement takes the form 

label ORG expression 

where "label" is an optional program label, and expression is a 16-bit 
expression, consisting of operands which are defined previous to the ORG 
statement. The assembler begins machine code generation at the location 
specified in the expression. There can be any number of ORG statements 
within a particular program, and there are no checks to ensure that the 
programmer is not defining overlapping memory areas. Note that most 
programs written for the CP/M system begin with an ORG statement of the 
form 

ORG 100H 

which causes machine code generation to begin at the base of the CP/M 
transient program area. If a label is specified in the ORG statement, then the 
label is given the value of the expression (this label can then be used in the 
operand field of other statements to represent this expression). 
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The END Directive 



The END statement is optional in an assembly language program, but if it 
is present it must be the last statement (all subsequent statements are 
ignored in the assembly). The two forms of the END directive are 



label 
label 



END 
END 



expression 



where the label is again optional. If the first form is used, the assembly 
process stops, and the default starting address of the program is taken as 
0000. Otherwise, the expression is evaluated, and becomes the program 
starting address (this starting address is included in the last record of the 
Intel formatted machine code "hex" file which results from the assembly). 
Thus, most CP/M assembly language programs end with the statement 

END 100H 

resulting in the default starting address of 100H (beginning of the transient 
program area). 



The EQU Directive 

The EQU (equate) statement is used to set up synonyms for particular 
numeric values. The form is 

label EQU expression 

where the label must be present, and must not label any other statement. 
The assembler evaluates the expression, and assigns this value to the 
identifier given in the label field. The identifier is usually a name which 
describes the value in a more human-oriented manner. Further, this name is 
used throughout the program to "parameterize" certain functions. Suppose 
for example, that data received from a Teletype appears on a particular input 
port, and data is sent to the Teletype through the next output port in 
sequence. The series of equate statements could be used to define these ports 
for a particular hardware environment 



TTYBASE EQU 10H 
TTYIN EQU TTYBASE 
TTYOUT EQU TTYBASE + 1 



BASE PORT NUMBER 
TTY DATA IN 
TTY DATA OUT 



FOR TTY 



At a later point in the program, the statements which access the Teletype 
could appear as 
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IN TTYIN ;READ TTY DATA TO REG - A 

OUT TTYOUT ; WRITE DATA TO TTY FROM REG-A 

making the program more readable than if the absolute I/O ports had been 
used. Further, if the hardware environment is redefined to start the Teletype 
communications ports at 7FH instead of 10H, the first statement need only 
be changed to 

TTYBASE EQU 7FH ;BASE PORT NUMBER FOR TTY 

and the program can be reassembled without changing any other 
statements. 

The SET Directive 

The SET statement is similar to the EQU, taking the form 

label SET expression 

except that the label can occur on other SET statements within the program. 
The expression is evaluated and becomes the current value associated with 
the label. Thus, the EQU statement defines a label with a single value, while 
the SET statement defines a value which is valid from the current SET 
statement to the point where the label occurs on the next SET statement. 
The use of the SET is similar to the EQU statement, but is used most often 
in controlling conditional assembly. 

The IF and ENDIF Directives 

The IF and ENDIF statements define a range of assembly language 
statements which are to be included or excluded during the assembly 
process. The form is 

IF expression 
statement #1 
statement #2 

statement #n 
ENDIF 

Upon encountering the IF statement, the assembler evaluates the 
expression following the IF (all operands in the expression must be defined 
ahead of the IF statement). If the expression evaluates to a non-zero value, 
then statement #1 through statement #n are assembled; if the expression 
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evaluates to zero, then the statements are listed but not assembled. 
Conditional assembly is often used to write a single "generic" program which 
includes a number of possible run-time environments, with only a few 
specific portions of the program selected for any particular assembly. The 
following program segments for example, might be part of a program which 
communicates with either a Teletype or a CRT console (but not both) by 
selecting a particular value for TTY before the assembly begins 

TRUE EQU OFFFFH ; DEFINE VALUE OF TRUE 
FALSE EQU NOT TRUE ;DEFINE VALUE OF FALSE 

TTY EQU TRUE ;TRUE IF TTY, FALSE IF CRT 



TTYBASE EQU 10H 
CRTBASE EQU 20H 
IF TTY 



;BASE OF TTY I/O PORTS 
;BASE OF CRT I/O PORTS 
;ASSEMBLE RELATIVE TO 
TTYBASE 
CONIN EQU TTYBASE ;CONSOLE INPUT 
CONOUT EQU TTYBASE + l;CONSOLE OUTPUT 
ENDIF 

IF NOT TTY ;ASSEMBLE RELATIVE TO 
CRTBASE 
CONIN EQU CRTBASE ;CONSOLE INPUT 
CONOUT EQU CRTBASE + l;CONSOLE OUTPUT 

ENDIF 

IN CONIN ;READ CONSOLE DATA 

OUT CONOUT ;WRITE CONSOLE DATA 

In this case, the program would assemble for an environment where a 
Teletype is connected, based at port 10H. The statement defining TTY could 
be changed to 

TTY EQU FALSE 

and, in this case, the program would assemble for a CRT based at port 20H. 



The DB Directive 

The DB directive allows the programmer to define initialized storage areas in 
single precision (byte) format. The statement form is 

label DB e#l,e#2, ...,e#n 
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where e#l through e#n are either expressions which evaluate to 8-bit values 
(the high order eight bits must be zero), or are ASCII strings of length no greater 
than 64 characters. There is no practical restriction on the number of expres- 
sions included on a single source line. The expressions are evaluated and placed 
sequentially into the machine code file following the last program address 
generated by the assembler. String characters are similarly placed into memory 
starting with the first character and ending with the last character. Strings of 
length greater than two characters cannot be used as operands in more 
complicated expressions (i.e., they must stand alone between the commas). 
Note that ASCII characters are always placed in memory with the parity bit 
reset (0). Further, recall that there is no translation from lower to upper case 
within strings. The optional label can be used to reference the data area 
throughout the remainder of the program. Examples of valid DB statements are 

data: DB 0,1,2,3,4,5 

DB data and 0ffh,5,377Q,l +2 + 3 + 4 

signon: DB 'please type your name',cr,lf,0 

DB 'AB' SHR 8, 'C, 'DE' AND 7FH 

The DW Directive 

The DW statement is similar to the DB statement except double precision 
(two byte) words of storage are initialized. The form is 

label DW e#l, e#2, ..., e#n 

where e#l through e#n are expressions which evaluate to 16-bit results. 
Note that ASCII strings of length one or two characters are allowed, but 
strings longer than two characters disallowed. In all cases, the data storage 
is consistent with the 8080 processor: the least significant byte of the 
expression is stored first in memory, followed by the most significant byte. 
Examples are 

doub: DW Offefh,doub + 4,signon-$,255 + 255 
DW 'a', 5, 'ab', 'CD', 6 shl 8 or lib 

The DS Directive 

The DS statement is used to reserve an area of uninitialized memory, and 
takes the form 

label DS expression 

where the label is optional. The assembler begins subsequent code 
generation after the area reserved by the DS. Thus, the DS statement given 
above has exactly the same effect as the statement 
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label: EQU $ ;LABEL VALUE IS CURRENT CODE LOCATION" 
ORG $ + expression ;MOVE PAST RESERVED AREA 

Operation Codes 

Assembly language operation codes form the principal part of assembly 
language programs, and form the operation field of the instruction. In 
general, ASM accepts all the standard mnemonics for the Intel 8080 
microcomputer, which are given in detail in the Intel manual 8080 Assembly 
Language Programming Manual. Labels are optional on each input line 
and, if included, take the value of the instruction address immediately before 
the instruction is issued. The individual operators are listed briefly in the 
following sections for completeness, although it is understood that the Intel 
manuals should be referenced for exact operator details. In each case, 

e3 represents a 3-bit value in the range of 0-7 which can be 

one of the predefined registers A, B, C, D, E, H, L, M, SP, 
or PSW. 

e8 represents an 8-bit value in the range 0-255 

el6 represents a 16-bit value in the range 0-65535 

which can themselves be formed from an arbitrary combination of operands 
and operators. In some cases, the operands are restricted to particular values 
within the allowable range, such as the PUSH instruction. These cases will 
be noted as they are encountered. 

In the sections which follow, each operation code is listed in its most general 
form, along with a specific example, with a short explanation and special 
restrictions. 



Jumps, Calls and Returns 

The Jump, Call and Return instructions allow several different forms which 
test the condition flags set in the 8080 microcomputer CPU. The forms are 

Jump unconditionally to label 
Jump on non zero condition to label 
Jump on zero condition to label 
Jump no carry to label 
Jump on carry to label 
Jump on parity odd to label 
Jump on even parity to label 
Jump on positive result to label 
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JMB 


el6 


JMP 


LI 


JNZ 


el6 


JMP 


L2 


JZ 


el6 


JMP 


100H 


JNC 


el6 


JNC 


Ll + 4 


JC 


el6 


JC 


L3 


JPO 


el6 


JPO 


$ + 8 


JPE 


el6 


JPE 


L4 


JP 


el6 


JP 


GAMMA 



JM 


el6 


JM al 


CALL 


el6 


CALL SI 


CNZ 


el6 


CNZ S2 


CZ 


el6 


CZ 100H 


CNC 


el6 


CNC SI + 4 


CC 


el6 


CC S3 


CPO 


el6 


CPO $+8 


CPE 


el6 


CPE S4 


CP 


el6 


CP GAMMA 


CM 


el6 


CM bl$c2 



Jump on minus to label 
Call subroutine unconditionally 
Call subroutine if non zero flag 
Call subroutine on zero flag 
Call subroutine if no carry set 
Call subroutine if carry set 
Call subroutine if parity odd 
Call subroutine if parity even 
Call subroutine if positive result 
Call subroutine if minus flag 

RST e3 RST Programmed "restart" equivalent to 

CALL 8*e3, except one byte call 

RET Return from subroutine 

RNZ Return if non zero flag set 

RZ Return if zero flag set 

RNC Return if no carry 

RC Return if carry flag set 

RPO Return if parity is odd 

RPE Return if parity is even 

RP Return if positive result 

RM Return if minus flag is set 

Immediate Operand Instructions 

Several instructions are available which load single or double precision 
registers, or single precision memory cells, with constant values, along with 
instructions which perform immediate arithmetic or logical operations on 
the accumulator (register A). 



MVI e3,e8 
ADIe8 


MVI 
ADI 


B.255 
1 


Move immediate data to register A, 
B, C, D, E, H, L, or M (memory) 
Add immediate operand to A with- 


ACIe8 


ACI 


OFFH 


out carry 

Add immediate operand to A with 


SUIe8 


SUI 


L + 3 


carry 

Subtract from A without borrow 


SBIe8 


SBI 


LAND11B 


(carry) 

Subtract from A with borrow (carry) 


ANIe8 


ANI 


$ AND 7FH 


Logical "and" A with immediate 
data 


XRIe8 


XRI 


lllllOOOOB 


"Exclusive or" A with immediate 
data 


ORIe8 


ORI 


LAND1+1 


Logical "or" A with immediate data 
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CPIe8 



CPI V 



LXIe3,el6 LXI B.100H 



Compare A with immediate data 
(same as SUI except register A not 
changed) 

Load extended immediate to register 
pair (e3 must be equivalent to 
B,D,H, or SP) 



Increment and Decrement Instructions 

Instructions are provided in the 8080 repertoire for incrementing or 
decrementing single and double precision registers. The instructions are 



INRe3 


INR 


E 


DCRe3 


DCR 


A 


INXe3 


INX 


SP 


DCXe3 


DCX 


B 



Single precision increment register 

(e3 produces one of A, B, C, D, E, H, 

L,M) 

Single precision decrement register 

(e3 produces one of A, B, C, D, E, H, 

L,M) 

Double precision increment register 

pair (e3 must be equivalent to 

B,D,H, or SP) 

Double precision decrement register 

pair (e3 must be equivalent to 

B,D,H, or SP) 



Data Movement Instructions 

Instructions which move data from memory to the CPU and from CPU to 
memory are given below 

MOV e3,e3 MOV A,B Move data to leftmost element 

from rightmost element (e3 
produces one of A, B, C, D, E, H, 
L, or M). MOV M,M is disallowed 

LDAX e3 LDAX B Load register A from computed 

address (e3 must produce either B 
orD) 

STAX e3 STAX D Store register A to computed 

address (e3 must produce either B 
orD) 

LHLD el6 LHLD LI Load HL direct from location el6 

(double precision load to H and 
L) 

SHLD el6 SHLD L5 + x Store HL direct to location el6 

(double precision store from H 
andL to memory) 
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LDA el6 


LDA Gamma 


STA el6 


STA X3-5 


POP e3 


POP PSW 


PUSH e3 


PUSHB 


IN e8 


IN 


OUT e8 


OUT 255 


XTHL 




PCHL 




SPHL 




XCHG 





Load register A from address el6 

Store register A into memory at 

el6 

Load register pair from stack, set 

SP (e3 must produce one of B, D, 

H, or PSW) 

Store register pair into stack, set 

SP (e3 must produce one of B, D, 

H, or PSW) 

Load register A with data from 

port e8 

Send data from register A to port 

e8 

Exchange data from top of stack 

with HL 

Fill program counter with data 

from HL 

Fill stack pointer with data from 

HL 

Exchange DE pair with HL pair 



Arithmetic Logic Unit Operations 

Instructions which act upon the single precision accumulator to perform 
arithmetic and logic operations are 



ADD e3 

ADC e3 
SUB e3 
SBB e3 

ANA e3 

XRA e3 
ORA e3 

CMP e3 

DAA 

CMA 



ADD B Add register given by e3 to ac- 

cumulator without carry (e3 
must produce one of A, B, C, D, E, 
H,orL) 

ADC L Add register to A with carry, e3 as 

above 

SUB H Subtract reg e3 from A without 

carry, e3 is defined as above 

SBB 2 Subtract register e3 from A with 

carry, e3 defined as above 

ANA 1 + 1 Logical "and" reg with A, e3 as 

above 

XRA A "Exclusiveor"withA,e3asabove 

ORA B Logical "or" with A, e3 defined as 

above 

CMP H Compare register with A, e3 as 

above 

Decimal adjust register A based 
upon last arithmetic logic unit 
operation 
Complement the bits in register A 
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STC Set the carry flag to 1 

CMC Complement the carry flag 

RLC Rotate bits left, (re)set carry as a 

side effect (high order A bit 
becomes carry) 
RRC Rotate bits right, (re)set carry as 

side effect (low order A bit 
becomes carry) 
RAL Rotate carry/A register to left 

(carry is involved in the rotate) 
RAR Rotate carry/A register to right 

(carry is involved in the rotate) 

DAD e3 DAD B Double precision add register 

pair e3 to HL (e3 must produce B, 
D, H, or SP) 

Control Instructions 

The four remaining instructions are categorized as control instructions, and 
are listed below 

HLT Halt the 8080 processor 

DI Disable the interrupt system 

EI Enable the interrupt system 

NOP No operation 

Error Messages 

When errors occur within the assembly language program, they are listed as 
single character flags in the leftmost position of the source listing. The line 
in error is also echoed at the console so that the source listing need not be 
examined to determine if errors are present. The error codes are 

D Data error: element in data statement cannot be 

placed in the specified data area 

E Expression error: expression is ill-formed and 

cannot be computed at assembly time 

L Label error: label cannot appear in this context 

(may be duplicate label) 

N Not implemented: features which will appear in 

future ASM versions (e.g., macros) are recognized, 
but flagged in this version 
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Overflow: expression is too complicated (i.e., too 

many pending operators) to compute; simplify it 

P Phase error: label does not have the same value on 

two subsequent passes through the program 

R Register error: the value specified as a register is not 

compatible with the operation code 

V Value error: operand encountered in expression is 

improperly formed 

Several error messages are printed which are due to terminal error conditions 



NO SOURCE FILE 
PRESENT 



The file specified in the ASM command does 
not exist on disk 



NO DIRECTORY SPACE The disk directory is full; erase files which are 

not needed, and retry 



SOURCE FILE NAME 
ERROR 

SOURCE FILE READ 
ERROR 



OUTPUT FILE WRITE 
ERROR 

CANNOT CLOSE FILE 



Improperly formed ASM file name (e.g., it is 
specified with "?" fields) 

Source file cannot be read properly by the 
assembler, execute a TYPE to determine the 
point of error 

Output files cannot be written properly, most 
likely cause is a full disk; erase and retry 

Output file cannot be closed, check to see if 
disk is write protected 
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LK 1 


H. SU 


.ADDRESS SUITCH TOGGLE 


MV I 


PI. 1 


.SET TO 1 FOR FIRST ITERATION 


L it I 


H, I 


.ADDRESS INDEX 


«'/ I 


n. e 


,1=8 



A Sample Session 

The following session shows interaction with the assembler and debugger in the 
development of a simple assembly language program. 

ASM SORT Assemble SORT. ASM 

CP/H ASSEMBLER - VER 1 8 

8 1 5C next free address 

883H USE FACTOR * of table used 00 to FF (hexadecimal) 

END OF ASSEMBLY 

DIR SORT • 

SORT ASM source file 

SORT BAK backup from last edit 

SORT PRN print file (contains tab characters) 

SORT HEX machine code file 

A>TYPE SORT PRN 

Source line 

machine code location ' SOftT PROGRAM IN CP/N ASSEMBLY LANGUAGE 

y . START AT THE BEGINNING OF THE TRANSIENT PROGRAM AC 

6168 < — ORG 1B8H 

generated machine code 

eiee 2i4eei< — ' sort 

8163 3681 
8185 214781 
8188 3688 

; COMPARE I UlTn ARRAY SIZE 

8I8A ?E COMP: MOV A, M .A REGISTER = I 

818B FEB9 CP1 N- 1 ,CY SET IF I < (N-l) 

8I8D D21981 JHC CONT .CONTINUE IF I <* <N-2) 

END OF ONE PASS THROUCH DATA 

8118 214681 LXI H, SU ;CHECK FOR ZERO SWITCHES 
8113 7E&7C288BI MOV A, M ! ORA A! JNZ SORT ,EHD OF SORT IF SU-8 

BUB FF RST 7 ;C0 TO THE DEBUGGER INSTEAD DF REt 

/' truncated 
CONTINUE THIS PhSS 
ADDRESSING I. SO LOAD AV(I) INTO REGISTERS 

8119 5F1 6BB21 48C0HT, MOV E.A! MVI D.8! LXI H.AVi DAD D! DAD D 
8121 4E752346 MOV CM! MOV A.Ci INX H! MOV B.M 

. LOU ORDER BYTE IN A AND C. HIGH ORDER BYTE IN 8 

MOV H AND L TO HDDRESS AV(IH) 

8125 23 INX H 

i 

■ COMPARE VALUE UITH REGS CONTAINING AV(I> 

8126 965778239E SUB M! MOV D.Ai MOV A, B ! INX H' SBB M ^SUBTRACT 

BORROU SET IF AV(I»1) > AV< I ) 
8126 DA3F81 JC INCI .SKIP IF IN PROPER ORDER 

CHECK FOK EQUAL VALUES 
812E B2CA1F8I ORB D' JZ I M r 1 .SKIP IF AV(l) » AV(l»t) 

8132 S6782B5E MOV D.M! MOV M.B! DCX Hi MOV E.n 

8136 712B722873 MOV M.CI DCX HI MOV M, D ' DCX H! MOV M, E 

. INCREMENT SWITCH COUNT 
813B 21468134 LXI H,SU< INR M 
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IIJF 21470I34C3INC1: 



9146 89 SU 

0147 I , 

8148 056964991EAV 

eeen « N 

1 5 c *^-— equate value 
A>TYPE SORT HEX 



INCREMENT I 

LXI H, I ' IHR n< JMP COHP 

DATA DEFINITION SECTION 

DB 8 .RESERVE SPACE FOR SylTCH COUNT 

DS 1 ;SPACE FOR INDEX 

DU 5. 188, 38, 58, 28, 7, 1888. 188,189, -32767 

EOU <»-AV>/2 ,COItPUTE N INSTEAD OF PRE 

EHD 



, 186 1888821 46813681 21478136 88 7EFEB9D21981 48 

,ieeil8ee214 6ei7EB7C2eeeiFF5F16882148eilS83 

100128 88 194E79234623965778239E0A3F81B2CAA7 

19ei38003F0l56702B5E712B722B732i468l34 21C7 

070I4009470134C30A01006E 

ieei48e8e5ee64eeiEee32Bei4eee7eeE8e32ceiBB 
: 848is8ee64eeeieeBE 

; 8888888888 

A>DDT SORT. HEX start debug run 

16K DDT VER 1 9 

NEXT PC 

015C 0888 default address (no address on END statement) 

-XP 



machine code 
■ in HEX format 



p-8099 199 changePCto 100 
- U F F F F untrace for 65535 steps 



abort with 
/rubout 



C0Z9H9E9I0 A-80 B-9900 0*8888 H-0900 S-0180 P-0180 LXI H, 8146*9189 
- T 10 trace 10 l6 steps 

cezenBEeie A-01 b^ 

cezeneE0i8 a-9i »< 

C9Z0N9E9I0 A-91 S- 

C0Z9H0E0I0 A-81 B' 

cez8H8E0ie a»bi b- 

C8Z8H8E8I8 A-99 B: 

C126NIE0I0 A-00 B> 

CIZBH1E0I0 A-00 B' 

cizeniEeie A-00 e 

C1Z0M1E0I0 A-91 B 

C9Z0M0E0I0 A-01 B 

C0Z0MBE0I0 A-01 B 

c0Z8neE0ie A-ei b- 

C8Z9HBE0ie A-81 6- 

C8Z8H8E8ie A-81 B' 

cezeHBEeie A-01 b 

-A18I 

81 0D JC 119 chanc 

oi ie 



8998 


D-0000 


H-0146 


S-0100 


p. 0199 


LXI 


H.8146 


9999 


0-9999 


H-9146 


S-0100 


P-8193 


HVI 


N, 81 


9008 


D>0009 


H-0146 


S-8199 


P-0105 


LXI 


H, 8147 


8800 


0-9990 


H-9147 


S-«100 


P-9188 


MVI 


H, 80 


0000 


D-0000 


H-9147 


S-0100 


P-0I0A 


HOV 


A, H 


9000 


D-0000 


H-0147 


S-0100 


P-8 IBB 


CPI 


09 


0000 


0=9999 


H-0147 


S-0100 


P-010D 


JHC 


0119 


0000 


D-0800 


H-0147 


S-0108 


p-8118 


LXI 


H, 0146 


0900 


D-8000 


H-0146 


S-8180 


P-8113 


NOV 


A, H 


0000 


D-0000 


H-0146 


S-0100 


P-0114 


0RA 


A 


0090 


D-0000 


H-0146 


S-0100 


P-0115 


JNZ 


8180 


9000 


D-0000 


H-0146 


S-0100 


p. 9100 


LXI 


H, 8146 


0000 


D>0000 


H-0146 


S-0100 


P-0103 


HVI 


H. 81 


0000 


D-0000 


H-01 46 


5*0100 


P-0105 


LXI 


H, 8147 


0000 


0=0000 


H-0147 


S-0100 


P-8188 


nvi 


n, 80 


00 


D-0000 


H - 9.1 4 7 


S-0100 


P-010A 


HOV 


A, n-91 


e to a jump on carry 






stopped at — ^ 
I0BH 



P * 1 B 10 reset program counter back to beginning of program 
-TIB trace execution for 10H steps 



C020H0E0I0 


A-00 


B-0000 


D-0000 


H-0147 


S-0100 


p. 0180 


LXI 


H.0146 


C0Z0H0E0I0 


A-00 


B-0000 


D-0000 


H-0146 


S-0100 


P-0103 


HVI 


H.01 


C0Z0H0E010 


A-80 


B-0000 


D-B900 


H-0146 


S-0100 


P-0103 


LXI 


H,0147 


C0Z0H8E010 


A-00 


B-0000 


D-9900 


H-0147 


S-0100 


P-8188 


HVI 


n, 00 


cBzeneEeie 


A-00 


B-0999 


0-8888 


H-0147 


S-0100 


P-818A 


HOV 


a.h 


C0Z0H0E010 


A-88 


3-9999 


0-9999 


H-0147 


S-0100 


P-019B 


CPI 


09 y 


C1Z0H1E0I0 


A-80 


3-9909 


0-9989 


H-0147 


S-0100 


P-8I9D 


JC 


0119 


C1Z9H1E9I9 


A-88 


B-9999 


0-8888 


H-0147 


S-0100 


P-0119 


HOV 


E, A 


cizeniE0i9 


A-80 


9-9000 


0-9909 


H-0147 


S-0100 


P-0 1 1 A 


MVI 


D. 00 


C1Z9H1E9I9 


A-00 


B-0000 


D-0000 


H-0147 


S-0100 


P-011C 


LXI 


H.0149 


C1Z0H1E9I9 


A-00 


B-0000 


D-0000 


H-9148 


S-9180 


P-011F 


DAD 


D 


C0Z0H1E0I0 


A-00 


B-9999 


D-0000 


H-914B 


S-9199 


P-0120 


DAD 


D 



altered instruction 
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tezeniEei e a»«8 e-aaea t-eeae n*eue s«ei*e p=eiii mov c.n 

cazaniEaie a»88 e-eea: D-aaaa H-aus s»ai«6 F=jiii hov n.c 

cezsniEeie a-85 B-aees D-aees d-iki s-aiaa p-»i23 inx h 

cazeniEaia a-83 B-seas D-eeee N-8149 s-eiee p-ei24 nov b,khi23 
-Liee * 



bibb 


LX1 


N.814« 


\ 


ei83 


HVI 


n.ei 


j 


lias 


LX1 


H,8147 


J 


aiaa 
eiaB 


nvi 

HOV 
CPI 


n, ea 

a. n 

89 


■ list some code 
V from 100H 


ei eo 


JC 


8119 


( 


ene 


LXI 


H.8146 


1 


ai 13 


HOV 


A.H 


1 


81 14 


OKA 


A 


1 


ei is 

-L 


JN2 


a i ee 


1 


ei 18 

81 19 


RST 
HOV 


e,a J. 


list more 


81 1A 


HVI 


o,ee I 




ai ic 


LXI 


H,ei48 * 




~ abort list with mbout 





Automatic 
breakpoint 



-G» 1 IB start program from current PC (01 25H) and run in real time to II BH 

* B 1 2 7 stopped with an external interrupt 7 from front panel (program was looping indefinitely) 
" * * look at looping program in trade mode . 

CBZBHBE818 A-38 B-B8C4 J-888« H-8136 S-81B8 P-8127 HOV I. A 
C8Z8H8E818 A-38 8-88(4 t-388* H-8136 S-ai«< P-8128 HOV A. 8 

cezanaEaie A-ae b-88<4 d-388« h-8iss s-aiee p-8129 inx n 

C8Z6H8C8I8 A-8B 6-8884 D-3BB6 H-8137 S-81B8 P-812A SBB H-612B 
-DI48 

^ data is sorted, but program doesn t stop 

8148 85 88 87 88 14 88 IE 88 

8118 32 88 (4 88 84 88 2C 81 E8 81 81 88 88 88 88 88 2 t S . 
8188 88 88 88 88 88 88 88 88 88 M 88 88 88 88 88 88 

- GO return to CP/M 

DBT SORT. HEX reload the memory image 

16K SOT VEft 1. • 
NEXT PC 
813C 8888 
-XP 

P-8B9B 188 Set PC to beginning of program 

-I.1M 

list bad opcode 

9188 JMC 811**^ 
8118 LXI H.8I46 

" abort list with rubout 

-A18J assemble new opcode 

918B JC 119 
81 IB 

-LI 88 list starting section of program 

8188 LXI H,8I46 
8183 HVI H,8t 
8185 LXI H.8I47 
8188 HVI n,b» 
' abort list with rubout 

- A 1 8 3 change "switch" initialization to 00 
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8103 NV1 H.8 

vies 

--C return to CP/M with ctlc (GO works as well) 

SAVE I SORT COM saw 1 page(256 bytes, from lOOHto lFFMH)ondisk in case 

we have to reload later 
A>»»T SORT. CON restart DDT with 

saved memory image 
16K L»T VER 1 B 
NEXT RC 

6200 0100 COM" file always starts with address 100H 
-G run the program from PC = 1 00H 



• 0110 programmed stop (RST 7) encountered 
-D14S 



data properly sorted 



0140 OS 00 07 00 14 00 IE 00 

0150 12 00 64 40 £4 00 2C 01 E8 •) 01 00 00 00 00 00 2 D 

0160 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 

0170 00 00 00 88 00 00 00 00 00 88 00 00 00 00 80 00 

- GO return to CP/M 

ED S R T . A S fl make changes to original program 

• H. Oram find next ".0" 



n, o 

H, 1 



HVI H,0 

* - up one line in text 

LX1 H,l 

* - up another line 

HVI II- 1 

»KT kill line and type next line 

LXI N.I 

* 1 insert new line 

HVI 

* T 

jn LX1 

•NjNcraoT 

JNC»T 
C0HT 

* -20IcQbLT 

JC 

* E . source from disk A 

/^ hex to disk A 
ASH SORT AAZ*~ skip pm file 

CR'H ASSEH0LER - VER 1 

015C next address to assemble 
083H USE FACTOR 
END OF ASSEMBLY 



.1-0 

/ADDRESS INDEX 

.SET TO 1 FOR FIRST ITERATION 

/ADDRESS INDEX 

;2ER0 SU 

/ADDRESS INDEX 



.CONTINUE IF 1 <- <N-2> 

C0NT .CONTINUE IF I <- (M-2> 



DDT SORT Hex test program changes 

UK DDT VER 1 

NEXT PC 

ii;[ eeee 
-g ieo 



• 01 1 a 
-D14S 



- data sorted 



0148 8S 80 07 00 14 00 IE 00 

0130 32 00 64 00 64 80 2C 81 E8 83 81 88 88 88 88 88 2 D D 
0168 00 00 88 88 86 88 88 88 88 88 88 68 00 88 88 »u 

- abort with rubout 

-CO return to CP/M — program checks OK. 
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CHAPTER 5 
CP/M Dynamic Debugging Tool 

• Introduction 

• DDT Commands 

• The A (Assemble) Command 

• The D (Display) Command 

• The F (Fill) Command 

• The G (Go) Command 

• The I (Input) Command 

• The L (List) Command 

• The M (Move) Command 

• The R (Read) Command 

• The S (Set) Command 

• The T (Trace) Command 

• The U (Untrace) Command 

• The X (Examine) Command 

• Implementation Notes 

• Sample Session 
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Introduction 

The DDT program allows dynamic interactive testing and debugging of 
programs generated in the CP/M environment. The debugger is initiated by 
typing one of the following commands at the CP/M Console Command level 

DDT 

DDT filename.HEX 

DDT filename.COM 

where "filename" is the name of the program to be loaded and tested. In both 
cases, the DDT program is brought into main memory in the place of the 
Console Command Processor (refer to the CP/M Interface Guide for 
standard memory organization), and thus resides directly below the Basic 
Disk Operating System portion of CP/M. The BDOS starting address, which 
is located in the address field of the JMP instruction at location 5H, is altered 
to reflect the reduced Transient Program Area size. 

The second and third forms of the DDT command shown above perform the 
same actions as the first, except there is a subsequent automatic load of the 
specified HEX or COM file. The action is identical to the sequence of 
commands 

DDT 

I filename.HEX or Ifilename.COM 

R 

where the I and R commands set up and read the specified program to test. 
(See the explanation of the I and R commands below for exact details.) 

Upon initiation, DDT prints a sign-on message in the format 

nnK DDT-s VER m.m 

where nn is the memory size (which must match the CP/M system being 
used), s is the hardware system which is assumed, corresponding to the codes 

D Digital Research standard version 

M MDS version 

I IMSAI standard version 

O Omron systems 

S Digital Systems standard version 

and m.m is the revision number. 
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Following the sign on message, DDT prompts the operator with the 
character "-" and waits for input commands from the console. The operator 
can type any of several single character commands, terminated by a carriage 
return to execute the command. Each line of input can be line-edited using 
the standard CP/M controls 

rubout remove the last character typed 

Control-X remove the entire line, ready for re-typing 
Control-C system reboot 

Any command can be up to 32 characters in length (an automatic carriage 
return is inserted as the 33rd character), where the first character determines 
the command type 

A enter assembly language mnemonics with operands 

D display memory in hexadecimal and ASCII 

F fill memory with constant data 

G begin execution with optional breakpoints 

I set up a standard input file control block 

L list memory using assembler mnemonics 

M move a memory segment from source to destination 

R read program for subsequent testing 

S substitute memory values 

T trace program execution 

U untraced program monitoring 

X examine and optionally alter the CPU state 

The command character, in some cases, is followed by zero, one, two, or three 
hexadecimal values which are separated by commas or single blank 
characters. All DDT numeric output is in hexadecimal form. In all cases, the 
commands are not executed until the carriage return is typed at the end of 
the command. 

At any point in the debug run, the operator can stop execution of DDT using 
either a Control-C or GO (jmp to location 0000H), and save the current 
memory image using a SAVE command of the form 
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SAVE n filename.COM 

where n is the number of pages (256 byte blocks) to be saved on disk. The 
number of blocks can be determined by taking the high order byteofthetop 
load address and converting this number to decimal. For example, if the 
highest address in the Transient Program Area is 1234H then the number of 
pages is 12H, or 18 in decimal. Thus the operator could type a Control-C 
during the debug run, returning to the Console Processor level, followed by 

SAVE 18 X.COM 

The memory image is saved as X.COM on the diskette, and can be directly 
executed by simply typing the name X. If further testing is required, the 
memory image can be recalled by typing 

DDT X.COM 

which reloads the previously saved program from location 100H through 
page 18 (12FFH). The machine state is not a part of the COM file, and thus 
the program must be restarted from the beginning in order to properly test 
it. 

DDT Commands 

The individual commands are given below in some detail. In each case, the 
operator must wait for the prompt character (-) before entering the 
command. If control is passed to a program under test, and the program has 
not reached a breakpoint, control can be returned to DDT by executing a 
RST 7 from the front panel (note that the rubout key should be used instead 
if the program is executing a T or U command). In the explanation of each 
command, the command letter is shown in some cases with numbers 
separated by commas, where the numbers are represented by lower case 
letters. These numbers are always assumed to be in a hexadecimal radix, and 
from one to four digits in length (longer numbers will be automatically 
truncated on the right). 

Many of the commands operate upon a "CPU state" which corresponds to 
the program under test. The CPU state holds the registers of the program 
being debugged, and initially contains zeroes for all registers and flags except 
for the program counter (P) and stack pointer (S), which default to 100H. 
The program counter is subsequently set to the starting address given in the 
last record of a HEX file if a file of this form is loaded (see the I and R 
commands). 
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The A (Assemble) Command 

DDT allows inline assembly language to be inserted into the current 
memory image using the A command which takes the form 

As 

where s is the hexadecimal starting address for the inline assembly. DDT 
prompts the console with the address of the next instruction to fill, and reads 
the console, looking for assembly language mnemonics (see the Intel 8080 
Assembly Language Reference Card for a list of mnemonics), followed by 
register references and operands in absolute hexadecimal form. Each 
successive load address is printed before reading the console. The A 
command terminates when the first empty line is input from the console. 

Upon completion of assembly language input, the operator can review the 
memory segment using the DDT disassembler. (See the L command.) 

Note that the assembler/disassembler portion of DDT can be overlayed by 
the transient program being tested, in which case the DDT program 
responds with an error condition when the A and L commands are used. 

The D (Display) Command 

The D command allows the operator to view the contents of memory in 
hexadecimal and ASCII formats. The forms are 

D 

Ds 

Ds,f 

In the first case, memory is displayed from the current display address 
(initially 100H), and continues for 16 display lines. Each display line takes 
the form shown below 

aaaa bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb cccccccccccccccc 

where aaaa is the display address in hexadecimal, and bb represents data 
present in memory starting at aaaa. The ASCII characters starting at aaaa 
are given to the right (represented by the sequence of c's), where non-graphic 
characters are printed as a period ( . ) symbol. Note that both upper and lower 
case alphabetics are displayed, and thus will appear as upper case symbols on 
a console device that supports only upper case. Each display line gives the 
values of 16 bytes of data, except that the first line displayed is truncated so 
that the next line begins at an address which is the multiple of 16. 
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The second form of the D command shown above is similar to the first, except 
that the display address is first set to address s. The third form causes the 
display to continue from address s through address f. In all cases, the display 
address is set to the first address not displayed in this command, so that a 
continuing display can be accomplished by issuing successive D commands 
with no explicit addresses. 

Excessively long displays can be aborted by pushing the rubout key. 

The F (Fill) Command 

The F command takes the form 

Fs,f,c 

where s is the starting address, f is the final address, and c is a hexadecimal 
byte constant. The effect is as follows: DDT stores the constant c at address 
s, increments the value of s and tests against f. If s exceeds f then the 
operation terminates, otherwise the operation is repeated. Thus, the fill 
command can be used to set a memory block to a specific constant value. 

The G (Go) Command 

Program execution is started using the G command, with up to two optional 
breakpoint addresses. The G command takes one of the forms 

G 

Gs 

Gs,b 

Gs,b,c 

G,b 

G,b,c 

The first form starts execution of the program under test at the current value 
of the program counter in the current machine state, with no breakpoints set 
(the only way to regain control in DDT is through a RST 7 execution). The 
current program counter can be viewed by typing an X or XP command. The 
second form is similar to the first except that the program counter in the 
current machine state is set to address s before execution begins. The third 
form is the same as the second, except that program execution stops when 
address b is encountered (b must be in the area of the program under test). 
The instruction at location b is not executed when the breakpoint is 
encountered. The fourth form is identical to the third, except that two 
breakpoints are specified, one at b and the other at c. Encountering either 
breakpoint causes execution to stop, and both breakpoints are subsequently 
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cleared. The last two forms take the program counter from the current 
machine state, and set one and two breakpoints, respectively. 

Execution continues from the starting address in real-time to the next 
breakpoint. That is, there is no intervention between the starting address 
and the break address by DDT. Thus, if the program under test does not 
reach a breakpoint, control cannot return to DDT without executing a RST 
7 instruction. Upon encountering a breakpoint, DDT stops execution and 
types 



where d is the stop address. The machine state can be examined at this point 
using the X (Examine) command. The operator must specify breakpoints 
which differ from the program counter address at the beginning of the G 
command. Thus, if the current program counter is 1234H, then the 
commands 

G,1234 
and 

G400.400 

both produce an immediate breakpoint, without executing any instructions 
whatsoever. 

The I (Input) Command 

The I command allows the operator to insert a file name into the default file 
control block at 5CH (the file control block created by CP/M for transient 
programs is placed at this location; see the CP/M Interface Guide). The 
default FCB can be used by the program under test as if it had been passed 
by the CP/M Console Processor. Note that this file name is also used by DDT 
for reading additional HEX and COM files. The form of the I command is 

Ifilename 
or 

Ifilename.filetype 

If the second form is used, and the filetype is either HEX or COM, then 
subsequent R commands can be used to read the pure binary or hex format 
machine code (see the R command for further details). 
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The L (List) Command 



The L command is used to list assembly language mnemonics in a particular 
program region. The forms are 

L 

Ls 

Ls,f 

The first command lists twelve lines of disassembled machine code from the 
current list address. The second form sets the list address to s, and then lists 
twelve lines of code. The last form lists disassembled code from s through 
address f. In all three cases, the list address is set to the next unlisted location 
in preparation for a subsequent L command. Upon encountering an 
execution breakpoint, the list address is set to the current value of the 
program counter (see the G and T commands). Again, long typeouts can be 
aborted using the rubout key during the list process. 



The M (Move) Command 



The M command allows block movement of program or data areas from one 
location to another in memory. The form is 

Ms,f,d 

where s is the start address of the move, f is the final address of the move, and 
d is the destination address. Data is first moved from s to d, and both 
addresses are incremented. If s exceeds f then the move operation stops, 
otherwise the move operation is repeated. 



The R (Read) Command 



The R command is used in conjunction with the I command to read COM 
and HEX files from the diskette into the transient program area in 
preparation for the debut run. The forms are 

R 
Rb 

where b is an optional bias address which is added to each program or data 
address as it is loaded. The load operation must not overwrite any of the 
system parameters from 000H through OFFH (i.e., the first page of memory ). 
If b is omitted, then b = 0000 is assumed. The R command requires a previous 
I command, specifying the name of a HEX or COM file. The load address for 
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each record is obtained from each individual HEX record, while an assumed 
load address of 100H is taken for COM files. Note that any number of R 
commands can be issued following the I command to re-read the program 
under test, assuming the tested program does not destroy the default area at 
5CH. Further, any file specified with the filetype "COM" is assumed to 
contain machine code in pure binary form (created with the LOAD or SAVE 
command), and all others are assumed to contain machine code in Intel hex 
format (produced, for example, with the ASM command). 

Recall that the command 

DDT filename.filetype 

which initiates the DDT program is equivalent to the commands 

DDT 

-Ifilename.filetype 

-R 

Whenever the R command is issued, DDT responds with either the error 
indicator "?" (file cannot be opened, or a checksum error occurred in a HEX 
file), or with a load message taking the form 

NEXT PC 
nnnn pppp 

where nnnn is the next address following the loaded program , and pppp is the 
assumed program counter (100H for COM files, or taken from the last record 
if a HEX file is specified). 



The S (Set) Command 



The S command allows memory locations to be examined and optionally 
altered. The form of the command is 

Ss 

where s is the hexadecimal starting address for examination and alteration 
of memory. DDT responds with a numeric prompt, giving the memory 
location, along with the data currently held in the memory location. If the 
operator types a carriage return, then the data is not altered. If a byte value 
is typed, then the value is stored at the prompted address. In either case, 
DDT continues to prompt with successive addresses and values until either 
a period (.) is typed by the operator, or an invalid input value is detected. 
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The T (Trace) Command 



The T command allows selective tracing of program execution for 1 to 65535 
program steps. The forms are 

T 

Tn 

In the first case, the CPU state is displayed, and the next program step is 
executed. The program terminates immediately, with the termination 
address displayed as 

*hhhh 

where hhhh is the next address to execute. The display address (used in the 
D command) is set to the value of H and L, and the list address (used in the 
L command) is set to hhhh. The CPU state at program termination can then 
be examined using the X command. 

The second form of the T command is similar to the first, except that 
execution is traced for n steps (n is a hexadecimal value) before a program 
breakpoint occurs. A breakpoint can be forced in the trace mode by typing 
a rubout character. The CPU state is displayed before each program step is 
taken in trace mode. The format of the display is the same as described in the 
X command. 

Note that program tracing is discontinued at the interface to CP/M, and 
resumes after return from CP/M to the program under test. Thus, CP/M 
functions which access I/O devices, such as the diskette drive, run in 
real-time, avoiding I/O timing problems. Programs running in trace mode 
execute approximately 500 times slower than real time since DDT gets 
control after each user instruction is executed. Interrupt processing routines 
can be traced, but it must be noted that commands which use the breakpoint 
facility (G, T, and U) accomplish the break using a RST 7 instruction, which 
means that the tested program cannot use this interrupt location. Further, 
the trace mode always runs the tested program with interrupts enabled, 
which may cause problems if asynchronous interrupts are received during 
tracing. 

Note also that the operator should use the rubout key to get control back to 
DDT during trace, rather than executing a RST 7, in order to ensure that the 
trace for the current instruction is completed before interruption. 
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The U (Untrace) Command 

The U command is identical to the T command except that intermediate 
program steps are not displayed. The untrace mode allows from 1 to 65535 
(OFFFFH) steps to be executed in monitored mode, and is used principally to 
retain control of an executing program while it reaches steady state 
conditions. All conditions of the T command apply to the U command. 

The X (Examine) Command 

The X command allows selective display and alteration of the current CPU 
state for the program under test. The forms are 

X 

Xr 

where r is one of the 8080 CPU registers 



c 


Carry Flag 


(0/1) 


z 


Zero Flag 


(0/1) 


M 


Minus Flag 


(0/1) 


E 


Even Parity Flag 


(0/1) 


I 


Interdigit Carry 


(0/1) 


A 


Accumulator 


(0-FF) 


B 


BC register pair 


(0-FFFF) 


D 


DE register pair 


(0-FFFF) 


H 


HL register pair 


(0-FFFF) 


S 


Stack Pointer 


(0-FFFF) 


P 


Program Counter 


(0-FFFF) 



In the first case, the CPU register state is displayed in the format 

CfZfMfEflf A = bb B = dddd D = dddd H = dddd S = dddd P = dddd inst 

where f is a or 1 flag value, bb is a byte value, and dddd is a double byte 
quantity corresponding to the register pair. The "inst" field contains the 
disassembled instruction which occurs at the location addressed by the CPU 
state's program counter. 

The second form allows display and optional alteration of register values, 
where r is one of the registers given above (C, Z, M, E, I, A, B, D, H, S, or P). 
In each case, the flag or register value is first displayed at the console. The 
DDT program then accepts input from the console. If a carriage return is 
typed, then the flag or register value is not altered. If a value in the proper 
range is typed, then the flag or register value is altered. Note that BC, DE, 
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and HL are displayed as register pairs. Thus, the operator types the entire 
register pair when B, C, or the BC pair is altered. 

Implementation Notes 

The organization of DDT allows certain non-essential portions to be 
overlayed in order to gain a larger transient program area for debugging large 
programs. The DDT program consists of two parts: the DDT nucleus and 
the assembler/disassembler module. The DDT nucleus is loaded over the 
Console Command Processor, and, although loaded with the DDT nucleus, 
the assembler/disassembler is overlayable unless used to assemble or 
disassemble. 

In particular, the BDOS address at location 6H (address field of the JMP 
instruction at location 5H) is modified by DDT to address the base location 
of the DDT nucleus which, in turn, contains a JMP instruction to the BDOS. 
Thus, programs which use this address field to size memory see the logical 
end of memory at the base of the DDT nucleus rather than the base of the 
BDOS. 

The assembler/disassembler module resides directly below the DDT 
nucleus in the transient program area. If the A, L, T, or X commands are used 
during the debugging process then the DDT program again alters the address 
field at 6H to include this module, thus further reducing the logical end of 
memory. If a program loads beyond the beginning of the 
assembler/ disassembler module, the A and L commands are lost (their use 
produces a "?" in response), and the trace and display (T and X) commands 
list the "inst" field of the display in hexadecimal, rather than as a decoded 
instruction. 

Sample Session 

The following example shows an edit, assemble, and debug for a simple 
program which reads a set of data values and determines the largest value in 
the set. The largest value is taken from the vector, and stored into "LARGE" 
at the termination of the program 



L^lTStoKT Of TRANSIENT AREA 
ilEHCTH OF VECTOR TO SCAN 
; LA»CER .EST VALUE $0 POD 
H.VECT ,g*S£ OF VECTOR 

■SET VftiUE 

-LARCER VALUE IN f> 
,UUHF IF IflUCER VALUE MOT FQUHD 
; characters HEP LARGEST VALUE. STORE IT TO C 
ItOV C, A 
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E> SCAN 


.ASH 




•I 




ytab charw 


tl 


ORG tl 


|»«H 




W 


t,±£M 




HVI 


La 


L.0itt--P 


.0.0. L 


Ul 


loaf, 1 ; 

rubout 1 


NOV 


AjJI 


ma 


X. 


deletes 


J2& 


MFOUHt 



NFOUND: 


IHX H 


-TO NEXT „E LEMHI Create Source 




DCR "5 


^SFsHrSP Program -underlined 




JH2 LOOP 






i 


END OF SON, STORE C by programmer. 




NOV a,c 


-GET LARGEST VALUE 




STA LARCE 






JJf J. 


;REBOOT 


7 


TEST DATA 




Vect, 


P_l 2,8,4,3 


5, 6, 1,5 


LEN 


EfiU f-VECT 


iLENGTH 


LARGE, 


IS 1 
.EM 


iLARCEST VALUE ON EXIT 






♦ B8P 








ORC 188H 


iSTART OF TRANSIENT AREA 




HV1 B,LEN 


iLENGTH OF VECTOR TO SCAN 




HV1 C-B 


^LARGEST VALUE SO FAR 




LXI H,VECT 


;BASE OF VECTOR 


LOOP: 


NOV A.N 


;CET VALUE 




sue C 


-LARGER VALUE IN C? 




JNC NF0UN1 


-JUMP IF LARGER VALUE NOT FOUND 


i 


NEU LARGEST VALUE, STORE IT TO C 




NOV C,A 




NFOUND 


1NX H 


;TO NEXT ELEHENT 




DCR B 


(BORE TO SCAN? 




JNZ LOOP 


-FOR ANOTHER 




END OF SCAN, STORE C 




NOV A,C 


GET LARGEST VALUE 




STA LARGE 






JNP B 


.REBOOT 


; 


TEST DATA 




VECT: 


DB 2,8, 4, 3 


5, 6, 1, 5 


LEN 


EOU <-VECT 


-LENGTH 


LARCE 


DS 1 
END 


-LARGEST VALUE ON EXIT 


•_E_ 


End of Edit 





Start Assembler 

CP'N ASSEMBLER - VER 1 B 



8122 

B82H USE FACTOR 
END OF ASSEMBLY 

TYPE SCAN PRN 



Assembly Complete — Look at Program Listing 



Code Address 



8188 
81*8 
9182 
8184 
8187 
81B8 
8189 

B1BC 
8181 
818E 
8I8F 



Machine Code 
8CBB ) 
8EB8' 
21198! 
7E 
91 
D28DB1 

4F 
23 
89 

C28781 



/ 



Source Program 

ORG 
NVI 

nvi 

LXI 
NOV 
SUB 
JNC 



NEU LARGEST 
NOV C, A 
IHX H 
DCR B 
JNZ LOOP 



ibbh 

B, LEN 

C, 8 

H, VECT. 
A, N 
C 
NFOUND 

VALUE 



;START OF TRANSIENT AREA 
iLENGTH DF VECTOR TO SCAN 
-LARGEST VALUE SO FAR 
-BASE OF VECTOR 
;CET VALUE 
-LARGER VALUE IH C 
-JUMP IF LARGER VALUE NOT FOUND 
STORE IT TO C 



TO NEXT 
NORE TO 



ELEMENT 
SCAN' 



FOR ANOTHER 



8112 79 

8113 322181 
BUS C3B8B8 

Code/data listing - 

truncated *■ - 

8119 82B884838SVECT: 



EHD OF SCAN, 



NOV 
STA 
JNP 



A, C 
LARGE 



STORE C 

,&ET LARGEE-T VALUE 



TEST DATA 
DB 2, 



I, 4, 3,5,6,1,5 
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ee«8 ■ «~. L€H EOU *-VECT .LENGTH 

a 121 Valueof) LARGE, IS 1 , LARGEST VALUE ON EXIT 

• 122 Equate END 



Start Debugger using hex format machine code 



A> 
DDT SCAN HEX 

UK DDT VER 1 8 
NEXT PC 

bi 21 eeee 

-x_ *^-^_^ — ■ last load address + 1 s next instruction 

/ to execute at 

cezeneEeie A-ee e-eeee D-eeee n-eeee s-eiee p>eeee out 7f pc=o 
-xp \ 

— Examine registers before debug run 

p. eeee lee 

Change PC to 100 

"£. Look at registers again f PC changed 

cezeneEeie A-ee e-eeee D-eeee H-eeea s-eiee p-eiee nvi B,e8«-^ 
- L lee Next instruction ^ 

to execute at PC =100 

eiee hvi e,ee 
Bie2 hvi cee 

B184 LXI H,eil9 

6167 HOV A,H f Disassembled Machine 

eiee SUB C ! CodeatlOOH 

8169 JNC eieD > (See Source Listing 

816C HOV C.A / for comparison) 

BieD INX H 

T18E DCR B 

S18F JNZ 6167 

8 112 MOV A.C 

-L_ 

til] STA 012 1 

Biu jtip eeee 

8 119 STAX B f A | ittte more 



611(1 NOP f machinec ode 



HIS INR 



(note that Program 



81 1C IN * B / ends at location 116 

91111 DCR B I with a JMP to 0000) 

611E NVI B.ei * 

B128 DCR 6 

e 1 2 1 LXI tl,2288 

8124 LXI H-82B8 

- A 1 1 6 enter inline assembly mode to change the JMP to 0000 into a RST 7, which 

will cause the program under test to return to DDT if 1 1 6H 

B I 1 6 RST 7 j s ever executed. 

B 1 I 7 (single carriage return stops assembly mode) 

- L 1 1 3 List Code at 1 13H to check that RST 7 was properly inserted 

in place of JMP 




-X. Look at registers 

cezeneEeie A-ee B-eeee o=eeee H-eeee s-eiee p*eiee hvi B.ee 

~ Execute Program for one step. initial CPU state, before / is executed 

cezeneEeie A=ee s-eeee D=eeee H-eeee s=eiee p-eiee hvi B,ee»ei62 

"~ Trace one step again (note 08H in B) automatic breakpoint -S 

cezeneEeie A-ee s-esee D-eeee H-eeee s-eiee p-eie2 hvi c.ee»eie4 
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ceze 
-12. 

ceze 
ceze 
ceze 
- mi 

ei 19 

B128 

ene 

8148 
8118 
8168 
8178 

eise 

8198 

sine 
etee 
eice 

-x 



Trace again (Register C is cleared) 

RBEeie A-ee B-e8ee B-eeee H-eeee s-aiee p-ete4 lxi 

Trace three steps 

hbebis a-bs B-68B8 o-eeee H-eii9 s-8iee p-bib? «ov 

(IBE8I8 A-82 B-88B8 1*8888 H-6I19 5=8188 P-8188 SUB 

H8E811 A-e2 B'8888 0-8888 H«eil9 S'8188 P-61B9 JNC 
9 



88 88 88 88 88 88 88 88 

ee ee ee ee ee ee ee ee 



Display memory starting at 1 19H. 

' 82 88 84 83 'eS 86 eT) Pro 9 ram data 

e5/i 1 88 22 21 B8 82 7E EB 77 13 23 EB 8B 

C2 27 81 C3 83 29 88 88 88 88 88 88 88 88 

88 88 88 88 

88 88 88 88 

ee ee ee ee ee ee ee ee ee ee ee ee ee 

ee ee ee ee ee ee ee ee 

ee ee ee ee 

ee ee ee ee ee ee ee ee ee 

ee ee ee ee ee ee ee ee ee ee ee ee ee ee 

ee ee ee ee ee ee ee ee ee ee ee ee ee ee 

ee ee ee ee ee ee ee ee ee 



Automatic breakpoint at 10DH 

- Lower case x 



h, ei i9-eie? 



a, n 

c 

eteD-eien 



■% 



ee ee ee ee 
ee ee ee ee 
ee ee ee ee 



ib ee 

ie ee 

e ee ee ee ee ee ee 

ie ee 



Data is displayed 
in ASCII with a ' " 
in the position of 
non-graphic 
characters 



ee ee ee 



Current CPU state 



cezeneEeii a-82 B-eeee D-eeee H-eii» s-eiee p-eteD ink 

-T5 



ceze 
ceze 
ceze 
ceze 
ceze 
-us 



Trace 5 steps from current CPU state 

neEeii A-B2 b-bbbb D-eeee h-bi 19 



£-8188 P-818D INX 



«8E8i i 0-82 B-88ee D-eeee H-eiiA s-eiee p-eteE dcr 

18E8I1 A-82 B-B7Be D-BBeB N-eilA S-Biee P-818F JNZ 

NBEeil A-B2 B-8788 D-B88B H-6I1A S-818B P-B187 NOV 

H8E811 A-88 B-B7BB D-BBBB H-B11A S-B1BB P-B1B8 SUB 



Trace without listing intermediate states 

ceziHBEiu A-ee B-e?ee D-eeee h-bua s-eiee p-eie9 jnc 

-*. CPU State at end of U5 > 



ceze 

-6. 

• em 

-x_ 

CBZ1 

-Sf 



HBE1I1 A-B4 B-B688 D-BBBB H-8118 S-B188 P-8188 SUB 
Run program from current PC until completion (in real-time) 
breakpoint at 1 16H. caused by executing RST 7 in machine code 



CPU state at end of program 
NBE111 A-8B B-8888 D-8888 H-8121 

examine and change program counter 
16 188 



B Automatic 

8 18 7 Breakpoint 
A, n 
C-8189 , 



eieD-eiee 



i-eiee p-eii6 rst b? 



ceziHBEiu A-ee B-eeee D-e 

"J-tE Trace 10 (hexadecimal) steps 

ceziHBEiu A-ee e-eeee i 

CBZ1HBEI11 A-ee B-BBBB 

C8Z1H8E1I1 A-l 

cezineEii 1 A-ee b 

cBzmeEiii A<ez\'Tf-eaeaHrseeee 



H=8i2i s-eiee p-eiee nvi Bee 



subtext for comparison 




first data element current largest value 

fee p-eiee nvi 

8i>*-"s-ei6e p»eie2 nvi 

121 s-eiee p-bi84 lxi 

ei l? s-eiee p-ei87 nov 

ei 19 s-eiee p=8183 sub 
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cezeneee: 1 

cezanesei 1 
cezeneEei i 
CBzenBEei i 
cezeneEei 1 
cezeneEei 1 
cbzinbeii 1 
cezinetii 1 
cbzihbeii l 
cezeneEii l 
cezeneEii 1 
-Dies 



I7B9 
I7B6 
1788 
1768 
I 788 
S7BB 

)6ee 

>68B 



0=88 

d=bb 
d = bb 

0=88 

D-ee 
o-ee 

= 86 

d = bb 

0=66 

0=6988 H = B1 IB 

D=BB 



I 19 
I 19 

I lft 
I 1ft 
1 1ft 
1« 
1ft 
lft 
IB 
II 
IB 



P=81B9 JN£_ 
P = 81BI> 



I NX 

S-81BB F=B1BE OCR 
3-8188 P=818F JHZ 
P=B 187 

P'Biee 

P=B189 JHC 
P=8!8D INX 
P-818E OCR 
P=818F 
8187 



=,= 8188 
$-8188 
5=81 88 
5=81 88 

s=eiee 
s=ei8e 

S=8168 



nov 

SUB 



JMZ 

nov 



Program should have moved the 
value from A into C since A)C. 
Since this code was not executed, 
it appears that the JNC should 
have been a JC instruction 



Insert a "hot patch ' into 
the machine code 
to change the 
JNC to JC 

- &8 Stop DDT so that a version of 

the patched program can be saved 

SftVE 1 SCftH . Con Program resides on first page, so save I page. 



Restart DDT with the saved memory image to continue testing 




«>»DT 


SCftN 


con Re 


16* IDT VES 1 8 


HEX! 


PC 




B2BB 


BIBB 




-nee 


List some code 


8 IBB 


nvi 


B, 86 


8182 


nvi 


C, 88 


eie? 


LX1 


H,eii9 


nov 


«, n / 


eiee 


SUB 


1 S 


8 189 


JC 


818D 


eiec 


nov 


I, k 


eieii 


IMX 


H 


8 1 BE 


set 


B 


eiBF 


JHZ 


8187 


8 112 


nov 


ft, C 


-XF 







. Previous patch is present in X-COM 



-Tie Trace to see how patched version operates 



Data is moved from A to C 



cezenaEBie 


n=ee 


8=8888 


0=6688 


►4 = 9689 


5=8168, 


* » 6 1 6 8 


nvi 


B. 88 


CBZBHBEBie 


ft=B8 


B'BBBB 


D>8BB8 


H=8889 


S = 8Lfrt 


P-9182 


nvi 


CB9 


cezeneEBie 


ft=88 


B=B8B6 


[1 = 8888 


H=8688 


s^rfee 


F=8164 


'.XI 


H,8113 


cezensEBie 


ft =88 


8=8888 


0=8888 


H = «l 15. 


-<=8i 68 


P=9167 


nov 


ft, n 


cezeneEBie 


*(fg 


J=e8B8 


0=8888 


H = 8L4"f 


5=9186 


P=9189 


SUB 


r 


CBZBNBEBI 1 


« = 82 


B"=*8B6 


0=889*' 


■%*$\ 19 


s=8iee 


P-8189 


JC 


8180 


c ezeneEBi 1 


ft>82 


B>raa6 


D»«tf86 


rt = 81 19 


5=8166 


P-61BC 


nov 


C- ft 


cezeneEei i 


« = 62 


8=e?(e|) 


0-6888 


H«81 19 


5=6189 


P=818D 


INK 


N 


CBZ8HBEB1 1 


0*82 


6=8882 


0=8888 


H = 61 lft 


5=91 B8 


P»B18E 


SCR 


8 


CBZBnBEBI 1 


ft»B2 


6=8782 


0=8888 


H>61 lft 


5=8186 


P=B18F 


JNZ 


8187 


CBZBnBEBI 1 


A = 62 


B=8782 


B=89B8 


H = 81 lft 


s=eiee 


F = 9 187 


nov 


ft, n 


cezeneEei i 


ft-ee 


6=6782 


0=8838 


H = ei lft 


5=8169 


p=8 168 


SUB 


c 


cizeniEeie 


ft = FE 


B-6782 


0=8888 


H = 81 lft 


5=8188 


P=8189 


JC 


8180 


ClZBniEBlB 


ft = FE 


6=6782 


0=6888 


H = 81 lft 


5=6186 


P=8 180 


INX 


H 


C 1 Z6N1E816 


ft = FE 


B=8782 


0=8888 


H = ei ib 


5=8186 


P-818E 


DCR 


8 


i izeneE ii i 


fl = FE 


B=8682 


0=8BBB 


H = 81 IB 


5=6189 


P=81BF 


JNZ 


8187*8187 



"21 breakpoint after 16 steps- 

ClZenBElll « = FE B=6692 11 = 8868 H == 8 1 IB 5 = 8188 P=8187 10V ft.n 
~ k • 196 R un f rom current PC and breakpoint at 108H 



- next data item 



ClZBneElM ft=84 B=8682 = 866 



=6196 P=9188 SUB 
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- Single step for a few cycles 

cizbmbehi s = 84 6=6682 n-eeee h = e i ie s=eie6 p=8iea 



>ub c»ei»9 



cezeiHBEeu »=ej B = B6B2 d=8666 h=8iib s=ei86 p»ei69 jc eiet«eiec 



C6Z6nBEeil « = B2 B=86B2 D=6888 H-81 IB i-BIBB P»816C NOV 
-G 



Run to completion 



• 9116 

-X 



cezmeem <i*e3 B=eee3 D^esee H=ei2i s=eiee p = a 1 1 6 rst b? 



-5_I_£_1 


look at the value of 'LARGE 


6121 


6 3 Wrong Value! 




6122 


BB 






B 1 23 


22 






B124 


21 






SI 25 


88 






6 1 2b 

11 1 2 ? 


^ End of the S comma 


-iie^ 








61 8 6 


HVI 


6, 83 n 


\ 


6182 


MVI 


C, 68 


\ 


6184 


LXI 


H, 6119 




Bl 8? 


MOV 


« . M 




8186 


SUB 






8189 


JC 


616H 




Bl BC 


MOV 


C, S 




BlBIi 


I NX 


H 




B1BE 


IlCR 


B 




61BF 


JNZ 


618? 




Bl 12 


/10V 


fl. C 


y Review the 


-L 






0113 


STB 


6 12 1 




91 It 


RST 


8? 




811? 


NOP 






81 18 


NOP 






SI 19 


STAX 


B 




31 Id 


NOP 






81 18 


INR 


B 




8 1 1C 


INX 


B 




81 It 


ICR 


6 




1 1 E 


MVI 


B, 61 




81 2B 


DCR 


b y 1 




-XP 









P = 6 1 1 £ 1_86 Reset the PC 

-J. Single step, and watch data values 



cezmBEiii « = 6 3 

-T 



B893 D=B88e H=8121 S=61B6 P=816e HVI B 83»B1B2 



H=8121 S= 1 6 



C6Z1MBE1I1 «=63 B=6863 D = 86 

- T count set 

~ / ^- — "largest set 

C6Z1M8E1I1 S=63 B=6886 [1=6666 H=6121 S = 61f 

- T 



P=8 162 HVI C . 66*8 164 



h Bi i 9»eie? 
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s~ base address of data set 
cbzimbeiii n=83 6=6866 ii = » 8 e » H=6ii9 5=6i&6 p.-eie? Nov « n«bi8b 

-T 

^ first data item brought to A 

CBZIMBEIII A-62 6=8866 B=866e H=6119 5-8186 P=8168 SUB C»61B9 
-X 

C6ZGM6E611 ft = 62 B=6S88 r.p = 6888 H = S l 19 5=8186 P=8169 JC 6I6D«6I8C 

-T_ 

C8Z6MBE6I1 H = 82 6=6868 B=8688 H=8119 5=8186 P=816C MOV C,««818D 
— x first data item moved to C correctly 

C6Z6MBE611 «=82 B=88B2 11=8886 H=6119 5=8186 P-818D 1 NX H«61BE 



C8Z6M8E611 ft=62 6=8362 0=6866 H-811H 5=8166 P=618E IlCR B»61BF 

-j_ 

CBZeneEBll « = 62 6=8782 D=B686 H=811ft 5=8188 P=818F JNZ 81B7»8187 

-T 

C6Z6M6E8I1 H=62 B=6762 0=6668 H = 1 1 1 H :-61tf6 P=61&7 M ./ ti,rl*6itf-d 

— s second data item brought to A 

C626M8EBI1 » = 86 B=8782 0=8886 H = 81lfl 5-8188 P=81B8 SUB C»B1B9 

— ^ subtract destroys data value which was loaded!!! 

ClZeMlEBlB H = FE B=6762 D=B686 H = 8 1 1 ft 5=8186 P=B169 JC 81BD«618D 

-T 

C1Z6M1E816 a = FE 6 = 6762 11=6888 H = 81 IB 5 = 8188 p=6!61i INX H»818E 
- 1166 

8186 MVI B . 68 
6 18 2 MVI C . 8 8 
81 84 LXI H, 8 1 1 9 

8187 MOV ft.M 

8 I 88 SUB C < This should have been a CMP so that register A 

8189 JC 618D would not be destroyed. 

6 18C MOV C,ft 

8 185 INX H 

616E DCR B 

818F JNZ 8167 

6 112 MOV ft , C 

- Ml69 

8 188 CMP C hot patch at 1 08H changes SUB to CMP 

6 1 69 

- C6 stop DDT for SAVE 

5HVE 1 SCHH COM 

save memory image 
h >MT SCftN. COM Restart DDT 

lcK BUT VER 1 8 
N E X T PC 
6286 6188 
"if 

P=61 86 
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t Look at code to see if it was property loaded 
(long typeout aborted with rubout) 



- L 1 1 6 

6116 KST 87 
A117 HOP 
CUIS HOP 
St 19 STAX 6 
GI1A HOP 
" (rubout) 

" c " * '^ Run from lOOHtocompietion 

• ens 

- X C Look at^arry (accidental typo) 



-*. Look at CPU state 

ciiineEiM u-es &=e*9f d = 9Ci&s H=ei2i i^oise p-sii* pst 

"iiili. Look at "Large" — it appears to be correct. 

SI 21 96 

C 1 22 e S 

S 1 2 3 2 2 , 

- 1^ stop DDT 

ED SCAH«ASH Re-edit the source program, and make both changes 

•SET / ct 

Sue/ C .LARGER VALUE IN C '■ 



ui^cn^e 



>incQc@»u 



C HP - C .LAPGER VALUE IN C '■ 



JHl NF0UHI) JUHP IF LARGER VALUE NOT FOyMJ 
"JT NFOUNt .JUMP IF LARGER VALUE MOT FOUND 

•X 

«SM SCAN AAT Re-assemble, selecting source from disk A 

~ ~ ~ hex to disk A 

CF-fl ASSEMBLER - VER 1 6 print to Z (selects no print file) 

'5122 

S & 2 H USE FACTOR 

EN5 OF ASSEMBLY 

['PI SCAN HEX Re-run debugger to check changes 

\iv lid T VER t 
mE.'T PC 

si2i eeee 

- 11 1 € 

Si lb *'MP see A check to ensure end is still at 11 6H 

SI 1 9 S T tt X B 
SUA NOP 
SUB INR 6 

- (rubout) 

- 1 6 S ■ 11 1 Go from beginning with breakpoint at end 
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*fflii breakpoint reached 

'1111 ,LOO ' K A "LARGE^__ corT ect value computed 

.Mil (3(6 8 22 21 Oti bl 71 E6 77 13 23 Ee *& 79 61 

:■ ; ib tz 2 7 ei C3 e3 2:- ee ee ee ee eG &e ee ee ee se 
:* < 4 g e e ee e e e e e e ee ee ee ee ee i? e ee ee ee ee ee 

(rubout) aborts long typeout 

*» stop DDT. debug session complete 
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